API reference#

Every name below is exported from the top-level pyvcad_medical package.

Color palettes#

pyvcad_medical.raw_color_palettes: dict[str, list[tuple[int, int, int]]]#

Named color palettes: "grayscale", "jet", "rainbow", "viridis", "cividis" and "magma". Each value is a list of (r, g, b) stops with channels in 0-255, ordered from the low end of the scale to the high end. Add an entry to make a custom palette available to get_color_palette().

pyvcad_medical.get_color_palette(name)[source]#

Returns a named palette from raw_color_palettes.

Parameters:

name (str) – Palette name: “grayscale”, “jet”, “rainbow”, “viridis”, “cividis” or “magma”.

Returns:

The palette’s (r, g, b) stops, with channels in 0-255.

Return type:

list[tuple[int, int, int]]

Raises:

ValueError – If no palette has this name.

Example

>>> import pyvcad_medical as med
>>> palette = med.get_color_palette("viridis")
pyvcad_medical.interp_color(palette, t)[source]#

Samples a palette at a normalized position.

The palette stops are spaced evenly over [0, 1] and adjacent stops are linearly interpolated.

Parameters:

  • palette (list[tuple[int, int, int]]) – (r, g, b) stops with channels in 0-255, such as a value from raw_color_palettes.

  • t (float) – Position in [0, 1]. Values of 1 or more return the last stop.

Returns:

The (r, g, b) color with channels in [0, 1].

Return type:

tuple[float, float, float]

Example

>>> import pyvcad_medical as med
>>> med.interp_color(med.get_color_palette("grayscale"), 0.5)
pyvcad_medical.lerp(a, b, t)[source]#

Linearly interpolates between two numbers.

Parameters:

  • a (float) – Value at t = 0.

  • b (float) – Value at t = 1.

  • t (float) – Interpolation parameter. Values outside [0, 1] extrapolate.

Returns:

a + (b - a) * t.

Return type:

float

Opacity curves#

pyvcad_medical.linear_opacity_base(t: float, ymin: float = 0.0, ymax: float = 1.0) → float[source]#

Linear opacity curve.

Parameters:

  • t (float) – Normalized position. It is clamped to [0, 1].

  • ymin (float) – Opacity at t = 0.

  • ymax (float) – Opacity at t = 1.

Returns:

ymin + (ymax - ymin) * t.

Return type:

float

pyvcad_medical.sigmoid_opacity_base(t: float, k: float = 10.0, x0: float = 0.5, ymin: float = 0.0, ymax: float = 1.0) → float[source]#

Sigmoid (S-curve) opacity curve.

Parameters:

  • t (float) – Normalized position in [0, 1].

  • k (float) – Steepness of the transition. Larger values give a sharper step.

  • x0 (float) – Midpoint of the transition in [0, 1].

  • ymin (float) – Lower bound of the output.

  • ymax (float) – Upper bound of the output.

Returns:

ymin + (ymax - ymin) / (1 + exp(-k * (t - x0))).

Return type:

float

pyvcad_medical.re_range_opacity(t: float, function, lower_opacity, upper_opacity) → float[source]#

Rescales an opacity curve to a new output range.

Parameters:

  • t (float) – Normalized position passed to function.

  • function (callable) – Base opacity curve f(t). Its result is clamped to [0, 1].

  • lower_opacity (float) – Output when function(t) is 0.

  • upper_opacity (float) – Output when function(t) is 1.

Returns:

lower_opacity + (upper_opacity - lower_opacity) * clamp(function(t)).

Return type:

float

Example

>>> import pyvcad_medical as med
>>> opacity = lambda t: med.re_range_opacity(t, med.sigmoid_opacity_base, 0.1, 0.9)
pyvcad_medical.plot_opacity_function(opacity_function, steps=100)[source]#

Plots an opacity curve over [0, 1] with matplotlib and shows the figure.

Parameters:

  • opacity_function (callable) – Opacity curve f(t).

  • steps (int) – Number of evenly spaced samples. Must be at least 2.

HU lookup tables#

pyvcad_medical.create_linear_gradient_hu_map(lower_hu, upper_hu, palette=[(37, 94, 199), (5, 255, 255), (255, 255, 0)], steps=20, opacity_function=<function <lambda>>)[source]#

Builds a Hounsfield-unit lookup table that sweeps through a color palette.

The range [lower_hu, upper_hu] is split into steps contiguous bins. Bin i takes the palette color at t = i / (steps - 1) and the opacity opacity_function(t).

Parameters:

  • lower_hu (float) – Lower HU bound of the first bin.

  • upper_hu (float) – Upper HU bound of the last bin.

  • palette (list[tuple[int, int, int]]) – (r, g, b) stops with channels in 0-255. Defaults to the “jet” palette.

  • steps (int) – Number of bins.

  • opacity_function (callable) – Opacity curve f(t) for t in [0, 1]. Defaults to a constant 1.0.

Returns:

One entry per bin, mapping an HU range to an RGBA Vec4.

Return type:

list[LookupTableEntry]

Example

>>> import pyvcad as pv
>>> import pyvcad_medical as med
>>> entries = med.create_linear_gradient_hu_map(100, 1000, palette=med.get_color_palette("rainbow"), steps=30)
>>> converter = pv.LookupTableConverter(["hu"], ["color_rgba"], entries, pv.InterpolationMode.STEP)
pyvcad_medical.plot_hu_color_map(hu_color_map, lower_hu=None, upper_hu=None, use_transparency=True)[source]#

Plots an HU lookup table as a horizontal color bar and shows the figure.

Each entry’s HU range is drawn at its true position and width; gaps between ranges are drawn transparent.

Parameters:

  • hu_color_map (list) – Entries ordered by HU, either LookupTableEntry objects or legacy ([lower_hu, upper_hu], color) pairs.

  • lower_hu (float, optional) – Left end of the bar. Defaults to the first entry’s lower bound.

  • upper_hu (float, optional) – Right end of the bar. Defaults to the last entry’s upper bound.

  • use_transparency (bool) – Draw each color with its alpha over a checkerboard. If False, colors are drawn opaque.

DICOM inspection#

pyvcad_medical.print_loaded_dicom_info(dicom_loader)[source]#

Prints a summary of a loaded DICOM series.

The summary lists the voxel size, the dimensions reported by get_dimensions(), the rescale slope and intercept, the HU range, and the bounding box of as_volume().

Parameters:

dicom_loader (DICOMLoader) – A loader that has read a series.

Example

>>> import pyvcad as pv
>>> import pyvcad_medical as med
>>> loader = pv.DICOMLoader("path/to/dicom_series")
>>> med.print_loaded_dicom_info(loader)