tryRgbHistogram256 - multiple declarations

Function tryRgbHistogram256

Build stored 8-bit R, G and B channel histograms over a nonempty ROI. This image-specific operation accepts exactly three channels already interpreted by the caller as R, G, B in that order. Planar, interleaved and signed-stride raster views are read through raster-d. It does not convert transfer functions, infer alpha, compute luma or assign units.

RgbHistogramError tryRgbHistogram256(
  scope raster.view.RasterView!(ubyte) rgb,
  raster.region.Region2D roi,
  ref RgbHistogram256 published
) @safe;

Unmasked channel counts use raster-d v0.3 histogram256 on a zero-copy ROI. The masked overload uses checked sample access because raster-d has no masked histogram. Both paths derive statistics from the exact bins.

The output is a fixed-size stack-compatible value; no pixel backing, cache, metadata graph or sample buffer is allocated. On every normally returned error, published retains its prior full value. Source storage must not be concurrently modified. No nothrow or OOM-Error promise.

Parameters

NameDescription
rgb Borrowed u8 R/G/B input, exactly three source planes.
roi Nonempty source-bounded rectangle.
published Complete statistics published only on success.

Returns

RgbHistogramError.none on success, otherwise a precise error.

Function tryRgbHistogram256

Build the same histogram with an explicit binary pixel-inclusion mask.

RgbHistogramError tryRgbHistogram256(
  scope raster.view.RasterView!(ubyte) rgb,
  raster.region.Region2D roi,
  scope raster.view.RasterView!(ubyte) selection,
  ref RgbHistogram256 published
) @safe;

selection is a borrowed one-channel u8 raster on the FULL source grid. A zero byte omits a pixel entirely; ANY nonzero byte (including 1, 128 or 255) includes each of its three channels exactly ONCE. This is NOT the fractional editing-strength behavior of the Levels mask. The mask is not inferred from alpha or NoData and is not retained after return.

All-excluded ROIs return success with zero bins and statistics. An invalid mask or failed sample read preserves published. See the unmasked overload's compiled example for both forms and failure handling.

Parameters

NameDescription
rgb Borrowed three-plane stored-u8 RGB input.
roi Nonempty rectangle in source coordinates.
selection Full-source-size one-plane inclusion mask.
published Output record, replaced only on success.

Returns

RgbHistogramError.none or an error preserving the previous record.