Skip to content

Add info about color and intensity to surface guide#993

Open
TimMonko wants to merge 1 commit intonapari:mainfrom
TimMonko:surface-colors
Open

Add info about color and intensity to surface guide#993
TimMonko wants to merge 1 commit intonapari:mainfrom
TimMonko:surface-colors

Conversation

@TimMonko
Copy link
Copy Markdown
Contributor

References and relevant issues

depends on napari/napari#8909

Description

Adds information about how colors are handled in surface layers, especially as it relates to contrast and colormaps.
Adds info relevant to napari/napari#8909 where color controls are disabled when vertex_colors is passed.
I tried also to clarify how omitting the vertex values resulted in 1s being used to color the surface, resulting in "white" and thus a bit of magic (to me) seemed to be involved in contrast controls and such. I still don't feel like I got the words out correctly.

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Apr 20, 2026
@TimMonko TimMonko added this to the 0.7.1 milestone Apr 20, 2026
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,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since there are several long components and one optional, changing to a bulleted list would reduce cognitive load for reader.

Comment on lines +83 to +85
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
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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
When the surface color is computed from `vertex_values`, controls related to `contrast limits`, `auto-contrast`, `gamma`, and
`colormap` are unavailable. If you provide `vertex_colors`, napari uses those colors

Is vertex_colors a vertex_value?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so this is IMO a bigger problem that I can address in the PR.
vertex_values is really the 3rd element of the data tuple, but it seems to be used throughout the docs and examples as if it were a real argument.
On the other hand, vertex_colors is an argument to Surface that overrides anything set in that third element of the data tuple.
I'll take another overall swing at the wording -- I think bulleting the tuple elements like above will probably help with this :)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No problem. I just didn't know the answer. Keep it simple now with just the bullets.

Comment on lines +127 to +134
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.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider a bullet list for sentences after the first.

Suggested change
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.
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.

Comment on lines +37 to +39
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.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

`(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
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here as above.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants