Image color processing
rbcImage.c contains greyscale conversion, gamma correction, a square-kernel filter and RGB palette reduction. These
CPU-side operations work on RBC color images, without renderer state or Tk callbacks. Their ownership and alpha policies
differ; they are not interchangeable image transformations.
Mutation and alpha
Operation |
Destination |
Alpha policy |
|---|---|---|
Greyscale |
Mutates the supplied image |
Preserved per pixel |
Gamma correction |
Mutates the supplied image |
Preserved per pixel |
Convolution |
Newly allocated, same-size image |
Set to 255 for every output pixel |
Quantization |
Existing equal-size image; may alias source |
Copied from the source pixel |
Caller-owned source images are never released by these routines. Convolution returns storage released with
Rbc_FreeColorImage(). Quantization allocates only temporary working storage and does not resize its destination.
See Image storage and tile clients for the underlying storage contract.
Greyscale and gamma
Greyscale uses 0.212671 * R + 0.715160 * G + 0.072169 * B, clamps to byte range and truncates, then writes the same
byte to all three color channels. It operates directly on stored channel values without first linearizing them.
rbcImageStorage.Rbc_GammaCorrectColorImage() builds a 256-entry lookup table using 255 * pow(value / 255, 1 /
gamma). It clamps and truncates each entry before applying the table independently to RGB. Gamma must be finite and
positive; invalid values panic. Neither operation changes alpha or dimensions.
Square-kernel filtering
Rbc_ConvolveColorImage() interprets Filter2D.support as a truncated integer radius with a minimum of
one. Even support zero therefore requires a 3-by-3 kernel. The caller provides a complete row-major square kernel; the
structure contains no length with which the function could verify that allocation.
At each output pixel, the code visits the neighborhood from top-left to bottom-right and consumes kernel coefficients in stored order. It does not reverse the kernel, so the operation is correlation in mathematical terminology; this distinction matters for asymmetric kernels. Coordinates outside the image repeat the nearest edge pixel.
RGB sums are divided by Filter2D.sum, clamped and truncated. The function does not calculate that divisor from the
coefficients, and Filter2D.scale is unused. Output alpha is opaque, regardless of source transparency. There is no
gamma conversion or premultiplied-alpha processing.
The implementation rejects missing kernel pointers, non-finite or negative support, excessively large support and non-finite or zero divisors by panicking. It does not validate coefficient values or kernel allocation length. Callers must supply finite coefficients and arithmetic that remains representable; these are private C preconditions, not Tcl error handling.
Palette reduction
Rbc_QuantizeColorImage() accepts a requested color count from 1 through 256 and an existing destination with
exactly matching dimensions. It returns TCL_ERROR for invalid count or mismatched dimensions without changing pixels
or producing an interpreter diagnostic. Empty images return TCL_OK.
The algorithm accumulates a 33-by-33-by-33 histogram with five bits per RGB channel and a zero boundary plane for cumulative moments. It records sample counts, channel sums and squared-color sums, then converts them into cumulative moments for box queries. Alpha is excluded from statistics: RGB in transparent pixels contributes equally to palette selection.
Color-space boxes are split using variance reduction. The requested count is an upper bound; splitting stops when no positive variance remains. Each box receives a representative color derived from its channel sums and population. There is no dithering or error diffusion. The histogram, box array and lookup table are released during the operation. Mapping can run in place because all statistics and palette construction finish before output overwrites pixels.
Palette lookup coordinates
Histogram construction, lookup-table population and pixel mapping all address channels as (value >> 3) + 1. Index
zero is reserved for cumulative-moment boundaries and is not a populated palette cell. Preserve this offset in every
stage: omitting it during mapping selects the preceding bin or a zero-filled boundary cell, turning colors with
low-valued channels black.
An empty palette box has a defensive stderr diagnostic and receives black; ordinary splitting rejects empty halves. Early termination below the requested palette size is normal and no longer emits a message. Neither case produces a Tcl interpreter diagnostic.
Quantizer stage contracts
The implementation follows the Wu-style greedy orthogonal partitioner credited in the source. Its statistics record has
five signed 64-bit arrays: population, three channel sums and squared-color sums. The squared sums use original 8-bit
RGB values even though bin addresses use five bits. rbcImageQuantization.GetColorImageStatistics() owns the
initial allocation; rbcImageQuantization.M3d() transforms it in place into prefix sums once. Reapplying
rbcImageQuantization.M3d() would accumulate already cumulative data and corrupt queries.
Each Cube describes a lower-exclusive, upper-inclusive interval on each axis.
The initial cube is (0, 32] on all three axes. Its geometric volume counts histogram cells, not pixels.
rbcImageQuantization.Volume() uses eight-corner inclusion-exclusion to query any one cumulative array.
rbcImageQuantization.Bottom() and rbcImageQuantization.Top() split that expression into a
cut-independent term and a term containing the proposed upper boundary.
rbcImageQuantization.Variance() is the squared-color sum minus the sum of squared channel totals divided by
population. It represents total squared error, or variance times population. rbcImageQuantization.Maximize()
omits the squared-color term because it is constant across a partition, and maximizes the combined mean-color scores of
the two halves. Candidate cuts with an empty half are skipped. Strict score comparison keeps the earliest winning cut;
rbcImageQuantization.Cut() resolves equal axis scores in red, green, blue order. These rules can affect
reproducibility even when several partitions have the same mathematical quality.
rbcImageQuantization.SplitColorSpace() owns a temporary variance array and writes into the caller’s cube
array. It splits the selected box, updates the two variances and chooses the first box with the largest positive
variance. A failed cut disables that box and retries the unused output slot. Geometric one-cell boxes are not split
again. Their pixels can still differ within the same five-bit bin, so asking for more colors does not guarantee recovery
of all distinct 8-bit RGB values. The requested color count is a cap, not an exact palette-size promise.
rbcImageQuantization.CreateColorLookupTable() computes each populated box’s channel means using integer
division. The legacy multiply-by-257 and right-shift-by-eight sequence preserves those byte means; it does not introduce
fractional rounding. rbcImageQuantization.Mark() fills every cell in the box with the packed representative
pixel. Mapping uses the partition cell directly rather than choosing the nearest palette color. This table is private
native Pix32 storage, not a portable serialized palette.
All histogram and palette construction finishes before destination pixels are written. Statistics and cubes are freed
before rbcImageQuantization.MapColors(), and the lookup table is freed
afterward. rbcImageQuantization.MapColors() saves source alpha before overwriting a pixel, which permits exact
in-place operation. It relies on the entry point’s equal-size validation; it is not independently safe for arbitrary
destination dimensions or partially overlapping storage.
The fixed histogram grid bounds indexing and geometric-volume arithmetic, but moment accumulation still requires representable signed 64-bit sums. Floating variance and score calculations use double and do not implement exact rational comparison or clamp cancellation artifacts. These helpers are private stages, not individually validating APIs for external callers.
Maintenance checks
Check pixel values as well as dimensions and return codes. Greyscale and gamma need alpha-preservation checks; convolution needs asymmetric kernels, edge replication, explicit divisors and opaque-alpha checks. Quantization needs solid colors with zero-valued channels, five-bit bin boundaries, alpha preservation, in-place output, fewer available colors than requested, and unchanged output on invalid arguments. Keep behavior fixes separate from comment-only changes.