ChimeraX-MorphometricsX

A ChimeraX bundle for loading quantified surface meshes (.vtp, VTK XML PolyData) produced by the surface_morphometrics cryo-ET pipeline (or other tools, like pycurv!), and coloring them by any stored per-triangle or per-vertex quantity — curvature, shape index, curvedness, membrane thickness, inter/intra distances, and more.

Features

• Opens .vtp directly — open surface.vtp or File ▸ Open. The reader is self-contained (pure Python + numpy); it does not depend on vtk or pyvista, so the bundle installs cleanly into ChimeraX's own interpreter. Opening a .vtp automatically brings up the MorphometricsX panel (in GUI mode, if it isn't already open).
• Color by any field stored in the file. Vector arrays (normals, principal directions) are also selectable per component or by magnitude — or pick a single solid color to show the surface uncolored by quantification.
• Adjustable colormap from ChimeraX's built-in set (diverging maps such as rdbu for signed curvature, sequential maps for magnitudes), with a gamma control for nonlinear emphasis (>1 emphasizes high values, <1 low values).
• Adjustable value range — auto (robust 2–98th percentile, made symmetric about zero for signed curvature fields), full data range, manual min/max, or an optional histogram with two draggable markers (like Volume Viewer's) that act as a low/high range slider. The histogram's display range is separately adjustable so extreme outliers don't compress the main distribution.
• Log scale toggle (off by default) that log10-transforms values for both the histogram and the coloring — useful for positive fields with wide dynamic range (curvedness, area, distances).
• Flat vs. smoothed shading. Flat unshares vertices so each triangle shows its exact per-cell value with no interpolation (faithful for quantitative work); smoothed averages onto shared vertices for a continuous gradient.
• Scale entry (default 1) that multiplies the surface coordinates, e.g. to convert a mesh stored in nm to Ångström (scale 10).
• Alpha slider + entry for surface opacity (0 transparent … 1 opaque).
• Color key — a checkbox displays a live-updating color key for the current field/colormap/range (it does not pop up the editor); a separate "Edit color key…" button opens ChimeraX's Color Key panel for position/size/font tweaks; a "Lighting…" button opens ChimeraX's Lighting panel (lighting, shadows and surface shininess).
• GUI panel (Tools ▸ Volume Data ▸ MorphometricsX) with hover tooltips and a Help button, plus a scriptable morphometricsx command that shares the state.

Installing

From the ChimeraX Toolshed (recommended) — in ChimeraX, open Tools ▸ More Tools…, find MorphometricsX, and click Install; or run toolshed install ChimeraX-MorphometricsX.

From a released wheel — download the .whl from the latest release and run toolshed install /path/to/chimerax_morphometricsx-<version>-py3-none-any.whl.

From source (for development):

ChimeraX --nogui --exit --cmd "devel install /path/to/ChimeraX-MorphometricsX ; exit"

or, in a running ChimeraX: devel install /path/to/ChimeraX-MorphometricsX.

Usage

Open a file and adjust it from the panel, or drive it from the command line:

open TF1_IMM.AVV_rh9.vtp

# List the colorable fields on the open surface(s)
morphometricsx list

# Color by mean curvature with a diverging map, auto range
morphometricsx color field mean_curvature_VV palette rdbu range auto

# Manual range and smoothed shading
morphometricsx color field shape_index_VV palette spectral range -1,1 shading smooth

# Available colormaps
morphometricsx palettes

morphometricsx color options

keyword	values	meaning
field	field name (e.g. mean_curvature_VV)	quantity to color by (cell field wins on tie)
palette	colormap name (e.g. rdbu, spectral)	colormap
range	auto | full | <low>,<high>	value range mapped to the colormap
gamma	float (1.0 = linear)	nonlinear colormap emphasis
log	true | false	log10-transform values for range + coloring
scale	float (1.0 = unchanged)	multiply surface coordinates (unit conversion)
alpha	float 0–1 (1 = opaque)	surface opacity
solid	a color (e.g. gray, red)	flat single color instead of coloring by field
normals	auto | geometric | vector field	which vectors drive the surface normals (advanced, command-line only)
shading	flat | smooth	per-triangle vs. smoothed

If no models are given, the command applies to every open MorphometricsX.

Surface normals

By default MorphometricsX lights surfaces using pycurv's per-triangle vector-voting normal (n_v) when the mesh carries it, falling back to geometric (winding-order) normals otherwise. Advanced users can override this from the command line:

morphometricsx color normals geometric        # force geometric normals
morphometricsx color normals avg_normals      # use any per-cell 3-vector field
morphometricsx color normals auto             # back to the default (n_v or geometric)

morphometricsx list reports the vector fields available as normals (e.g. n_v, normal, avg_normals, t_1, t_2). This option is intentionally not in the GUI.

Notes

• ChimeraX ships a ChimeraX-VTK bundle whose (save-only) "VTK PolyData" format also claims .vtp. MorphometricsX registers a distinct openable format ("Morphometrics surface", nickname morphovtp) for the same suffix, so open file.vtp routes to this bundle. To force it explicitly, use open file.vtp format morphovtp.
• The reader supports the writer variant emitted by surface_morphometrics (PolyData, appended data, base64 encoding, zlib compression, UInt32/UInt64 headers) plus the raw/uncompressed appended fallbacks. Inline/ASCII DataArray encodings are not supported.