Video alpha channel missing: preserve masks for vision

A transparency flag in a video file does not prove that your application receives transparent pixels. The decoder, pixel converter, capture wrapper, or display stage can remove or ignore alpha independently. This troubleshooting procedure is for synthetic inspection scenes, overlay playback, and repeatable vision tests. You will locate the first boundary that loses alpha, verify its numerical meaning, and choose between an alpha-preserving decoding path and synchronized colour-plus-mask files.

1. Establish what is missing before changing settings

Start with the most likely cause: an application interface returning colour-only frames. A file can advertise transparency while the array delivered to your inspection code contains only colour channels.

Record these properties for one known reference frame:

• File dimensions, frame rate, and presentation timestamp.
• Selected decoding backend and its version.
• Decoder output pixel format, including any separate alpha plane.
• Application array shape, element type, channel order, and row stride.
• Minimum and maximum alpha values, if alpha reaches the application.

Distinguish decoded pixels from container metadata. A transparency declaration describes how the file should be interpreted; it does not demonstrate that the selected decoder reconstructs transparency. Likewise, a requested output format describes your request, not necessarily the actual returned buffer.

Use a reference clip containing a fully transparent area, a fully opaque area, and a partially transparent edge. Without known transparent content, an entirely opaque alpha plane is inconclusive.

If the application receives an interleaved array with three colour channels, alpha is absent from that array. However, three channels alone do not prove that the decoder discarded it: alpha might still exist in a separate buffer.

For interpreting array layout, the related pixel-format and array-type troubleshooting guide explains why dimensions and element types must agree with the actual buffer.

2. Find the first boundary that loses transparency

Trace one frame through the pipeline rather than changing several settings together. Inspect the decoder output before colour conversion, then inspect the application buffer before rendering or image processing.

Treat channel order and alpha association as separate questions. Knowing where alpha is stored does not tell you whether the colour values are straight or premultiplied.

When a requested format differs from the delivered format, use the same boundary-by-boundary approach described in camera pipeline format negotiation. File decoding has different controls, but checking the actual output contract remains essential.

3. Choose a decoding path that actually exposes alpha

A switch that disables automatic colour conversion is not a universal transparency switch. Depending on the backend, it might return native colour planes, packed colour data, or another representation without exposing alpha.

Follow this sequence:

1. Check the selected backend's documented support for the file's codec and transparency representation.
2. Confirm whether alpha is returned as an interleaved channel, a separate plane, or an auxiliary decoded frame.
3. Request an explicitly supported alpha-bearing output format when the interface provides that option.
4. Read back the negotiated format and inspect the returned buffer.
5. Run the known reference clip before processing production test data.

If the decoder exposes alpha but the high-level capture interface does not, use a documented decoding interface that returns the required planes. Another legitimate option is an offline export into a representation your existing application can read without ambiguity.

Do not assume that converting a colour-only buffer to four channels recovers transparency. That operation commonly creates a new alpha channel with a constant opaque value. The original coverage information cannot be reconstructed from that conversion alone.

Use supported releases and documented configuration methods. A custom software patch is not a prerequisite for a reliable synthetic-test workflow; exporting colour and mask frames separately often provides a simpler interface to validate.

4. Test alpha values, not just channel count

Four channels are necessary for some interleaved alpha formats, but they are not proof of valid transparency. The extra channel could contain padding or generated opacity.

For unsigned 8-bit alpha, conventional opacity values run from 0 for transparent to 255 for opaque. Other element types require their own documented scale. For example, normalized floating-point alpha commonly uses 0 to 1; do not apply an integer threshold blindly.

For a known test frame, measure:

• Minimum and maximum alpha.
• Number of fully transparent pixels.
• Number of fully opaque pixels.
• Number of intermediate values.
• Alpha at several reference coordinates.

An illustrative unsigned 8-bit test is:

confirm documented channel order
alpha = extract documented alpha channel or plane
assert alpha width and height match the colour image
report minimum(alpha), maximum(alpha)
report count(alpha == 0)
report count(alpha == 255)
report count((alpha > 0) and (alpha < 255))

A known transparent region that returns 255 everywhere points toward lost transparency or incorrect interpretation. An all-zero result can indicate the wrong plane, incorrect extraction, or an actually transparent frame. Reference coordinates distinguish those cases.

Inspect row stride as well. A buffer can include padding after each row, and a separate alpha plane can have its own stride. Read each plane according to its declared layout rather than assuming tightly packed storage.

Do not classify pixels using the RGB values hidden beneath transparency. Fully transparent pixels can retain arbitrary colour data. For the downstream display stage, see image overlays with transparency and masks, which covers how colour and coverage should be combined.

5. Export synchronized masks when the capture interface cannot carry alpha

Separate colour and mask frames are a practical fallback when your inspection application accepts images but its video interface drops alpha. Decode through a path that demonstrably preserves transparency, then export the colour image and alpha plane together.

The export should produce a manifest with:

• A stable frame identifier.
• The source presentation timestamp and its time base.
• Colour-frame and mask-frame filenames.
• Width, height, and orientation.
• Mask element type and opacity scale.
• Straight or premultiplied colour interpretation.

Use lossless storage for the mask when exact opacity values matter. Avoid passing it through an ordinary colour-video encoder without validating the decoded result. Lossy compression, range conversion, and colour processing can change mask values.

Pair frames by recorded identity and timestamp, not by independent playback counters. Variable timing, seeking, or dropped frames can make two apparently matching frame numbers refer to different moments.

For a constant-rate example, the nominal interval at 25 frames/s is:

A mask shifted by one frame is therefore displaced by 40 ms in this example. If an object moves at 500 pixels/s, the apparent edge error is:

That error can resemble a segmentation failure even though the individual masks are correct. For variable-rate material, use presentation timestamps rather than this constant-rate estimate.

If you need binary inspection regions, define how opacity becomes membership. A threshold of 128 on unsigned 8-bit alpha is one possible convention, not a universal ground-truth rule. Keep the original alpha plane so you can revise that decision later. The live binary image preview guide helps with checking the resulting inspection mask.

6. Separate missing alpha from incorrect compositing

Correctly decoded alpha can still produce a misleading preview. A viewer might ignore transparency, assume the wrong colour order, or apply straight-alpha mathematics to premultiplied colour.

For straight alpha, the basic compositing equation is:

Here, F is foreground colour, B is background colour, and C is the composite. This normalization applies to unsigned 8-bit alpha.

For a numerical example, assume linear intensity values represented on a 0–255 scale. With foreground intensity 200, background intensity 40, and alpha 128:

Premultiplied colour already includes multiplication by alpha. Its equation instead uses the stored premultiplied foreground directly:

Multiplying that foreground by alpha again darkens partially transparent edges. Conversely, treating straight colour as premultiplied can create bright fringes.

Use a dark and a light test background to expose edge errors. For physically meaningful colour blending, account for the colour encoding and perform blending in linear light. Blending encoded display values directly is not generally equivalent.

7. Verify the fix and prevent regression

Verification should cover the complete file, not just its first frame. A pipeline can appear correct initially and fail after seeking, buffering, or a format transition.

Run this acceptance checklist:

• Reference pixels: Confirm transparent, opaque, and intermediate values at known coordinates.
• Channel order: Use distinct colour patches so channel swaps are visible.
• Dimensions and stride: Check every plane against its declared layout.
• Timing: Match colour and mask timestamps throughout playback.
• Seeking: Repeat the test after a seek and after reopening the file.
• Storage: Reload exported masks and compare them with the decoded originals.
• Rendering: Composite over contrasting backgrounds and inspect moving edges.
• Repeatability: Save backend versions, export settings, and interpretation rules with the dataset.

For a lossless mask export, pixel-for-pixel equality is a useful acceptance condition. If a conversion changes bit depth or scale, define the conversion and permitted error explicitly instead of expecting equality.

Keep playback, inference, and display timing measurements separate. A slow preview does not prove that decoding has dropped alpha. Likewise, a correct displayed image does not prove that your inspection algorithm received the mask.

When recording the test output, also verify that the writer opens successfully and is finalized correctly. The empty recording file troubleshooting guide addresses that separate failure mode.

8. Size the replay station after the format works

Do not replace hardware to solve a software interface that discards alpha. First establish a working decoding or export path; then measure its memory, processing, and storage demands.

For scale, an unpacked colour-plus-alpha stream with four unsigned 8-bit channels has this payload rate:

This is an illustrative decoded payload, not a compressed-file rate or a controller performance claim. Additional copies, temporary conversion buffers, and processing outputs increase memory traffic.

For a camera-connected replay station, browse vision controllers only after defining the required interfaces and measuring the workload. The MV-VC3301H-128G66 is a catalogued controller option to evaluate against those requirements.

The MV-VC2140-128G40-1T is another catalogued vision-controller option. Neither product listing establishes compatibility with your decoding backend; validate the software stack and application workload separately.

Once the reference clip passes, keep it as a regression test beside the exported dataset. For help matching a controller to a verified replay workload, send the measured payload, camera interfaces, and decoding requirements through applications support.