Convert image RGB pixels to grayscale with luminance weighting

Convert image RGB samples to grayscale without uploading a file or depending on an image decoder. Supply an ordered array of pixels, each with red, green, and blue channel values, and receive the same number of pixels with all three output channels set to a luminance-weighted gray value. The conversion emphasizes green, then red, then blue to better reflect perceived brightness than a simple average. Every input channel is validated, so incomplete pixels, nonnumeric values, and values outside the standard zero-to-255 range fail clearly instead of producing misleading output.

Prepare complete RGB sample records

Channel values may be integers or fractional numbers, but each must be finite and fall between zero and 255 inclusive. The converter deliberately requires every channel on every record. Preserve the original pixel order when constructing the array.

A single request can contain up to one hundred thousand samples. Split larger rasters into deterministic chunks and concatenate their returned sample arrays in request order. This interface works on decoded samples rather than PNG, JPEG, or WebP bytes, so decode files before calling it and encode the returned RGB records afterward if a new image file is required.

Understand the luminance-weighted calculation

For each sample, the converter calculates gray as the nearest integer to 0.299 times red plus 0.587 times green plus 0.114 times blue. These coefficients sum to one, keep neutral input pixels neutral, and account for the fact that human vision generally perceives green light as contributing more brightness than red and substantially more than blue. A plain arithmetic mean would assign equal importance to all three channels and can make saturated blue pixels look too bright or saturated green pixels too dark.

After computing the weighted value, the converter rounds once to the nearest whole channel value. It then writes that same number into r, g, and b in the returned record. Equal output channels create a neutral RGB gray without introducing a color cast.

The response also includes the sample count and a formula string, making automated logs and test reports self-describing. The function is pure: it uses no network requests, random values, current time, external model, or mutable cross-request state. If a color-managed scientific workflow requires those operations, apply them before or after this narrowly defined conversion.

Use the result safely in image pipelines

On success, read the response samples array as a positional replacement for the input samples array. Each returned record has r, g, and b set to the computed gray, so consumers expecting ordinary three-channel RGB data can accept it without a separate grayscale pixel format. The count field provides a quick integrity check: compare it with the number of records submitted before rebuilding a row, tile, thumbnail, or complete raster.

Keep those values alongside your request rather than expecting the service to infer them from a flat sequence. Alpha is intentionally absent from the contract; if the source image has transparency, retain its alpha buffer independently and combine it with the converted channels during encoding. Validation errors are useful pipeline guards.

Treat missing-channel, nonfinite-number, range, and array-size failures as data-quality problems rather than retryable service errors. Correct the decoded buffer or chunking logic before calling again. Together those cases catch weight changes, rounding differences, channel-order mistakes, and accidental weakening of validation.