Float image to JPEG: prevent black output with scaling

A floating-point slice can look correct in a preview yet become nearly black after JPEG encoding. This usually means the preview and encoder interpreted the same numbers differently. For image-processing and inspection integrations, the first task is to separate intensity conversion from compression and transport. You will check the actual slice, choose an explicit display range, create unsigned 8-bit pixels, and verify a local round trip before investigating the receiver.

Start with numeric range, not the socket

The most likely cause is a range mismatch. A floating-point preview may interpret values between zero and one as a complete brightness range. A common JPEG encoding path expects unsigned 8-bit pixel values between zero and 255.

If a codec wrapper converts small floating-point values directly into integer samples, most brightness information can disappear. Other implementations may reject floating-point input instead. Do not depend on an implicit conversion or assume every library version behaves identically.

Check these causes in order:

Once you have a valid display image, the separate image bytes versus pixel data guide explains the compressed-buffer boundary. Here, the main question is what pixel values entered that buffer.

Inspect the exact slice passed to the encoder

Log the array immediately before encoding, not several processing stages earlier. Record its shape, dtype, minimum, maximum, and count of non-finite values. Also inspect representative interior samples, since abbreviated array output can hide everything except the borders.

A correct decoded shape does not prove that the original intensities survived. Dimensions and brightness values are separate properties.

For a computed array, establish what its numbers mean:

• A normalized intensity may use a fixed range from zero to one.
• A camera-derived array may retain a larger integer scale after conversion to floating point.
• A filtered response may contain negative values.
• A complex-valued transform may require magnitude, phase, real, or imaginary components.
• A depth or measurement array may contain physical quantities rather than brightness.

Taking the absolute value of complex data produces its magnitude and discards phase. That can be a valid visualization decision, but it is not merely a storage conversion. Decide which quantity you need before defining its brightness mapping.

Also check for NaN and infinite values. Rejecting an invalid frame is often safer than silently painting invalid measurements black. If a preview needs an invalid-data marker, define that behavior separately from the numerical record.

Choose a mapping before converting float image to JPEG

For a real-valued display quantity, map a chosen interval onto the available output range:

Here, x is the source value, low and high define the display interval, and p becomes an unsigned 8-bit sample. The upper bound must exceed the lower bound.

Worked example: fixed versus adaptive scaling

Suppose a slice contains values from 0.08 to 0.72 and represents normalized intensity. With fixed bounds of zero and one:

• The darkest sample becomes round(255 × 0.08) = 20.
• The brightest sample becomes round(255 × 0.72) = 184.
• A sample of 0.40 becomes 255 × 0.40 = 102.

The image should remain moderately dark because the source never reaches full scale.

Per-frame scaling gives a different answer. Setting low = 0.08 and high = 0.72 maps the endpoints to zero and 255. The same 0.40 sample becomes round(255 × (0.40 - 0.08) / 0.64) = 128.

Neither mapping is universally correct. Fixed bounds preserve brightness comparisons; adaptive bounds emphasize each frame's internal contrast. Constant-valued slices need special handling under adaptive scaling because their range is zero.

Apply explicit scaling, clipping, and conversion

The following Python example accepts a real-valued grayscale array. It rejects invalid input, creates a contiguous unsigned 8-bit image, and checks the codec locally.

import cv2
import numpy as np


def jpeg_preview(values, low=0.0, high=1.0, quality=95):
    source = np.asarray(values)
    if np.iscomplexobj(source):
        raise TypeError("Choose a real-valued quantity explicitly")

    source = np.asarray(source, dtype=np.float64)
    if source.ndim != 2 or source.size == 0:
        raise ValueError("Expected a nonempty grayscale array")
    if not np.isfinite(source).all():
        raise ValueError("Source contains non-finite values")
    if not np.isfinite([low, high]).all() or high <= low:
        raise ValueError("Display bounds must be finite and increasing")
    if not 0 <= quality <= 100:
        raise ValueError("JPEG quality must be between 0 and 100")

    unit = np.clip((source - low) / (high - low), 0.0, 1.0)
    pixels = np.ascontiguousarray(
        np.rint(255.0 * unit).astype(np.uint8)
    )

    ok, encoded = cv2.imencode(
        ".jpg", pixels, [cv2.IMWRITE_JPEG_QUALITY, quality]
    )
    if not ok:
        raise RuntimeError("JPEG encoding failed")

    payload = encoded.tobytes()
    decoded = cv2.imdecode(
        np.frombuffer(payload, dtype=np.uint8),
        cv2.IMREAD_UNCHANGED,
    )
    if decoded is None or decoded.shape != pixels.shape:
        raise RuntimeError("JPEG round-trip validation failed")

    return pixels, payload, decoded


source = np.linspace(0.08, 0.72, 64, dtype=np.float32).reshape(8, 8)
pixels, payload, decoded = jpeg_preview(source)

for name, array in [
    ("source", source),
    ("encoder input", pixels),
    ("decoded", decoded),
]:
    print(name, array.shape, array.dtype, array.min(), array.max())

The order matters: scale in floating point, clip, round, then convert to the integer dtype. Casting before scaling destroys fractional information. Casting without clipping can also produce unintended values rather than the desired saturation behavior.

A grayscale image does not need replicated color channels for this encoding path. Converting grayscale into three channels changes its representation, not its numeric range. Add color conversion only when a downstream interface actually requires it.

The contiguous copy makes the encoder input layout explicit when the source originated from a strided slice. It does not correct brightness; the preceding intensity mapping does that.

Verify the local round trip with numbers

Compare the original numerical array, the unsigned 8-bit encoder input, and the decoded image separately. The second comparison isolates JPEG behavior from your chosen visualization mapping.

JPEG is lossy, so decoded pixels need not equal encoder-input pixels. Calculate differences after widening the integer type to avoid unsigned subtraction errors:

error = np.abs(decoded.astype(np.int16) - pixels.astype(np.int16))
print("maximum absolute pixel error:", error.max())
print("mean absolute pixel error:", error.mean())

Set acceptable error limits from the application, not from a universal threshold. Smooth previews, sharp edges, and isolated bright pixels respond differently to compression. Raising quality does not make JPEG lossless.

For a control test, encode the same unsigned 8-bit image as PNG and decode it unchanged. That grayscale round trip should preserve the pixel values exactly. If both formats look wrong, inspect the display mapping before blaming JPEG.

A one-column slice is also difficult to judge visually. Enlarge only its preview using nearest-neighbor display scaling, while retaining the original numerical samples. For profile-based inspections, the row-summing intensity profile guide explains a more useful numerical representation than a thin picture.

Preserve measurement data separately from previews

Use JPEG for a human-readable preview when compression artifacts are acceptable. Do not use it as the authoritative record of floating-point measurements, complex data, or exact pixel intensities.

Keep two outputs when both purposes matter:

1. A numerical record containing the original dtype, dimensions, values, units, and processing metadata.
2. A display image containing the selected mapping, clipping bounds, and any visualization adjustments.

A floating-point-capable TIFF workflow or an array-oriented format may serve the numerical record, but confirm support in both the writer and reader. A filename extension alone does not establish that the original dtype survived.

PNG can preserve the integer pixels you give it without JPEG artifacts. It does not automatically preserve the original floats after you have scaled and quantized them.

For camera intensity records, saving higher-bit-depth images without losing intensity data addresses the related storage decision. If an integer export develops regularly missing intensity levels, investigate periodic gaps in image histograms rather than adjusting display contrast to conceal them.

Investigate transport only after the local test passes

Once local encoding and decoding work, send the exact encoded byte payload. Do not reshape compressed bytes into image dimensions: the decoder reconstructs pixels from the encoded stream.

At the receiver, verify payload length, decode success, image dimensions, channel count, and dtype. Comparing a payload digest at both endpoints can establish whether the bytes changed during transfer.

For stream sockets, define message framing, byte order, and a maximum accepted payload length. A single send or receive operation need not transfer an entire image. Accumulate the declared payload before decoding, and handle partial transfers explicitly.

For message-oriented middleware, follow its documented message-boundary and buffer-lifetime rules. In C++, keep externally owned receive storage valid for every operation that references it. Copy when ownership or lifetime cannot be guaranteed.

If the identical payload decodes locally but not remotely, then library configuration, buffer construction, or transport handling becomes the appropriate next investigation.

Separate acquisition hardware from export behavior

This fault can occur downstream of either GigE or USB3 acquisition. Changing the camera interface does not replace a missing intensity conversion.

If you are also selecting acquisition hardware, compare area scan cameras through the camera finder. The LS-CMR-0053 uses GigE. The LS-CMR-0166 uses USB3. Treat these as acquisition options, not codec fixes.

When comparing vision controllers, verify the documented runtime, camera interfaces, and codec support needed by your application. Reproduce the conversion test on the deployment target before committing to an integration. Product category membership alone does not establish software compatibility.

For an existing installation, first correct and validate the software path. Purchase decisions should follow acquisition and deployment requirements, not a black preview caused by array scaling.

Prevention checklist before deployment

• Define the source quantity. Document whether values represent intensity, magnitude, depth, or another measurement.
• Declare display bounds. Store fixed bounds with the application configuration and record any adaptive policy.
• Handle invalid data deliberately. Reject it or mark it according to an explicit visualization rule.
• Check encoder input. Confirm a nonempty shape, intended channels, unsigned 8-bit dtype, and expected range.
• Test representative cases. Include dark, bright, constant, signed, and narrow slices where applicable.
• Validate locally first. Check encoding status, decoded statistics, and compression error before adding transport.
• Keep numerical originals. Do not let a preview replace the measurement record.
• Repeat tests after deployment changes. Codec builds and runtime behavior can differ between systems.

If the range or deployment behavior remains unclear, bring a small numerical sample, its dtype, chosen display bounds, and local round-trip statistics to integration support. If acquisition hardware is also changing, start with the camera configurator after establishing the required numerical output.