Diagnostics Module

Histograms for checking scores and rendered images.

Each function writes a matplotlib figure to disk.

Score Histograms

terrain_maker.terrain.diagnostics.generate_score_histogram(raw_scores, transformed_scores, output_path, cmap_name='boreal_mako', transform_label='Normalized + Gamma', rendered_max=None, rendered_min_nonzero=None, gamma=1.0, normalize_scores=False, print_cmap_name=None, title=None)[source]

Generate a side-by-side histogram of raw and transformed scores with colormap-colored bars.

Left panel shows the raw score distribution with bars colored by their eventual colormap color (applying the normalization + gamma pipeline to each bin center). Middle panel shows the transformed score distribution with bars colored directly by their position on the colormap. Optional right panel shows the same transformed distribution with the print-safe colormap for visual comparison.

Parameters:

  • raw_scores (ndarray) – Raw score array (2D grid, may contain NaN).

  • transformed_scores (ndarray) – Scores after normalization + gamma (2D grid, may contain NaN).

  • output_path (Path) – Path to save the histogram image.

  • cmap_name (str) – Matplotlib colormap name for coloring bars.

  • transform_label (str) – Label describing the transformation (e.g. “Normalized, gamma=0.5”).

  • rendered_max (float | None) – Max score in the rendered region (used for normalization reference lines).

  • rendered_min_nonzero (float | None) – Min nonzero score in the rendered region.

  • gamma (float) – Gamma value used in the transformation.

  • normalize_scores (bool) – Whether –normalize-scores stretch was applied.

  • title (str | None) – Figure title naming what the scores are (default: generic raw vs transformed).

  • print_cmap_name (str | None) – Optional print-safe colormap name. When provided, a third panel is added showing the transformed scores with print-safe colors.

Returns:

Path to the saved histogram image, or None on failure.

Return type:

Path | None

Raw scores beside the same scores after the normalization used for coloring (and optionally the print-safe colormap), with bars colored by the colormap.

Example:

from terrain_maker.terrain.diagnostics import generate_score_histogram

generate_score_histogram(
    raw_scores=scores,
    transformed_scores=normalization.apply(scores),
    output_path="histograms/scores_as_rendered.png",
    cmap_name="boreal_mako",
    title="Base scores as rendered",
)

Render Histograms

terrain_maker.terrain.diagnostics.generate_rgb_histogram(image_path, output_path)[source]

Generate and save an RGB histogram of a rendered image.

Creates a figure with histograms for each color channel (R, G, B) overlaid on the same axes with transparency. Useful for analyzing color balance and distribution in rendered outputs.

Parameters:

  • image_path (Path) – Path to the rendered image (PNG, JPEG, etc.)

  • output_path (Path) – Path to save the histogram image

Returns:

Path to saved histogram image, or None if failed

Return type:

Path | None

RGB channel histograms of a rendered image, for checking color balance and range.

terrain_maker.terrain.diagnostics.generate_luminance_histogram(image_path, output_path)[source]

Generate and save a luminance (B&W) histogram of a rendered image.

Shows distribution of brightness values with annotations for pure black and pure white pixel counts. Useful for checking exposure and clipping in rendered outputs, especially for print preparation.

Parameters:

  • image_path (Path) – Path to the rendered image (PNG, JPEG, etc.)

  • output_path (Path) – Path to save the histogram image

Returns:

Path to saved histogram image, or None if failed

Return type:

Path | None

Luminance histogram of a rendered image, for checking exposure and contrast.

See Also