From 1febf5d6914c8a0e4365ef7303d45237b1711a06 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Mon, 20 Apr 2026 13:41:07 -0500 Subject: [PATCH] update surface guide --- docs/howtos/layers/surface.md | 46 ++++++++++++++++++++++++++++------- 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/docs/howtos/layers/surface.md b/docs/howtos/layers/surface.md index 858ee2c3b..fc26547cc 100644 --- a/docs/howtos/layers/surface.md +++ b/docs/howtos/layers/surface.md @@ -33,9 +33,10 @@ layer first, then explore the GUI controls. The surface layer allows you to display a precomputed surface mesh that is defined by an `NxD` array of `N` vertices in `D` coordinates, an `Mx3` integer -array of the indices of the triangles making up the faces of the surface, and a -length `N` list of values to associate with each vertex to use alongside a -colormap. +array of the indices of the triangles making up the faces of the surface, and, +optionally, a length `N` list of values to associate with each vertex to use +alongside a colormap. If you omit the vertex values, napari uses a length `N` +array of ones. ## A simple example @@ -79,6 +80,13 @@ viewer.close() Once you have created a `surface` layer programmatically, the following GUI controls are available in the viewer: +Controls related to `contrast limits`, `auto-contrast`, `gamma`, and +`colormap` are only available when the surface color is computed from +`vertex_values`. If you provide `vertex_colors`, napari uses those colors +directly and disables those controls because they no longer affect rendering. +When a texture is present, napari multiplies the texture by the underlying +surface color. + - **Buttons** - Pan/zoom - ![image: Pan/zoom tool](../../_static/images/pan-zoom-tool.png) is the default mode of the layer and supports panning and zooming. Press the `1` key when the @@ -116,12 +124,27 @@ help(napari.Viewer.add_surface) ## Surface data -The data for a `surface` layer is defined by a 3-tuple of its vertices, faces, -and vertex values. The vertices are an `NxD` array of `N` vertices in `D` -coordinates. The faces are an `Mx3` integer array of the indices of the -triangles making up the faces of the surface. The vertex values are a length `N` -list of values to associate with each vertex to use alongside a colormap. This -3-tuple is accessible through the `layer.data` property. +The data for a `surface` layer can be given as either a 2-tuple +`(vertices, faces)` or a 3-tuple `(vertices, faces, vertex_values)`. The +vertices are an `NxD` array of `N` vertices in `D` coordinates. The faces are +an `Mx3` integer array of the indices of the triangles making up the faces of +the surface. The optional vertex values are a length `N` list of scalar values +to associate with each vertex for colormap-based rendering. If you omit +`vertex_values`, napari fills them with ones, so the default underlying surface +color is white. + +## How surface colors are computed + +- `vertex_values` are mapped through the selected `colormap`. `contrast limits`, + `auto-contrast`, and `gamma` all operate on this scalar-coloring path. +- `vertex_colors` provide direct per-vertex colors and override any color that + would otherwise come from `vertex_values`. When `vertex_colors` are present, + the GUI disables the scalar-coloring controls because they do not affect the + rendered surface. +- `texture` plus `texcoords` multiplies the texture color by the underlying + surface color. If that underlying color comes from `vertex_values`, the + scalar-coloring controls still affect the result. If it comes from + `vertex_colors`, they do not. ## 3D rendering @@ -176,3 +199,8 @@ what values get applied the minimum and maximum of the colormap and follow the same principles as the `contrast_limits` described in the [image layer guide](layers-image). They are also accessible through the same keyword arguments, properties, and GUI layer controls as in the image layer. + +These controls only apply when the surface is colored from `vertex_values`. +That includes textured surfaces whose texture is multiplied by a color derived +from `vertex_values`. They do not apply when the surface is colored directly by +`vertex_colors`.