imaqWriteAVIFrame incompatible image size: fix the buffer

Your grabber runs, the writer accepts every frame, and the clip plays solid black — or the very first write fails with 'incompatible image size'. Both symptoms have one root: the image you passed to the writer holds no acquired frame. This guide is for engineers recording frame-grabber video from C code that uses the imaq function set. You will see why a freshly created image reports 0 × 0 pixels, why forcing its size makes the error disappear and the video go black, and how to wire acquisition so every written frame carries real pixels. A worked PAL example gives you the file-size arithmetic to prove a clip is complete before you ship the recorder.

What the writer actually checks

Before storing a frame, the writer compares your image with the AVI stream it opened. Width and height must be non-zero and equal to the stream's dimensions, and the pixel format must be one of the two it stores. 'Incompatible image size' pins the failure to the first check: the image you passed reports no usable dimensions, typically (0, 0).

That is not a settings problem in the writer — it is a statement about your buffer. The image exists as an object, but no acquisition has ever filled it, so the writer refuses to size a video around it. The fix is not a different size. It is giving the image a frame.

Why imaqCreateImage returns (0, 0)

imaqCreateImage builds a header: pixel type, border size, ownership. It allocates no pixels and stores no dimensions. Everything else arrives when data is copied into the image — and the call that copies is the acquisition itself. A grab or snap into that image writes the sensor data and sets the image's width and height to the acquisition window in one step. A (0, 0) reading straight after creation is normal, not a bug.

The fault appears one step later, when the code writes that untouched image. If creation itself fails instead of returning an empty header, that is a different problem — diagnose frame grabber buffer allocation errors covers allocation failures.

Why imaqsetImageSize gives you black frames

imaqsetImageSize changes the header's dimensions and nothing else. It does not allocate pixels, convert formats or copy a byte of video. After you set (640, 480) by hand, the writer's dimension check passes, every frame is accepted, and each stored frame is a header-sized block with no pixel content behind it: black. The file grows with duration exactly as a live recording would, because the frames exist — only their content is empty.

File size cannot reveal the black frames either. Uncompressed, every frame stores all its pixels, black ones included, so a full-length black clip and a full-length live clip are the same size on disk. Judge frames by pixel values, never by bytes.

Likely causes, in order of probability

Work down the table; the first three rows account for most cases, and each test takes under a minute.

Rows 1 and 2 are the buffer hand-off that current interfaces make explicit too: frame grabber image acquisition for Camera Link and CoaXPress walks through how a frame grabber hands buffers to your code.

The fix: acquire into the image, then write

1. Create the image in the pixel type you will write: 8-bit grayscale for a mono grabber, 32-bit RGB for color. Raw transport bytes and pixel planes are different things — image bytes vs pixel data: decode before processing explains the distinction.
2. Configure the session and start acquisition: video standard PAL, acquisition window sized for your scene.
3. Grab or snap one frame into that image before you open the AVI. The call copies sensor data in and sets the image size to the window in the same step.
4. Read the width and height back from the image. Non-zero, and equal to your acquisition window, means the buffer is real; on a full PAL window that is 576 lines by 768 pixels for square-pixel capture, or 720 pixels at ITU-R BT.601 sampling.
5. Open the writer at that width, height and type, then write each frame immediately after its grab — always the same image, always in order. Recording continuously? Grab into a ring and write each buffer while it is still yours, the pattern in save an image sequence from a frame grabber with a ring buffer.
6. Close the writer when the loop ends. The index players rely on is written at close, so a skipped close can leave a full file unplayable; if the file exists but holds no frames at all, empty camera recording file: check writer setup and cleanup works that failure.

Two documented writer rules: image type and even height

The writer stores 8-bit grayscale and 32-bit RGB images and rejects other formats with its own type error, as the function's documentation notes on incompatible image types. A mono analog grabber delivers 8-bit gray and fits directly; convert 16-bit or planar color frames before writing.

Playback adds a second rule: keep the frame height even. Some decoders render an odd-height file as black even though every pixel is stored, a behavior the knowledge base documents for AVI files that play back black. PAL's 576 lines are even, so a full window is safe; round any region-of-interest crop to an even line count. If a file will not open at all — rather than opening black — that is a container or decoder problem, and video capture backend fallback: diagnose AVI open errors works through it.

Worked example: does the file size add up

Take a full square-pixel PAL window at 8-bit gray. Width × height: 768 × 576 = 442,368 bytes per frame, about 442 kB. PAL runs at 25 frames per second, so one second of video is 442,368 × 25 = 11,059,200 bytes — roughly 11.1 MB/s, or 663 MB per minute (11,059,200 × 60 = 663,552,000). A 10-second clip stores 250 × 442,368 = 110,592,000 bytes, about 111 MB.

Use the number twice. If your uncompressed 10-second clip lands near 111 MB, all 250 frames were written — now sample pixels to prove they are live, because black frames cost the same bytes. If the clip holds a few kB, the writes were rejected or never called, and the causes table above is your next stop.

When the grabber itself is the legacy problem

A PCI grabber of that generation runs on the driver stack it shipped with. On a current 64-bit Windows build, loading that driver is usually the first failure, and no recording code revives a driver its vendor no longer maintains. If this recorder is part of a new line, move acquisition to a current interface and keep the same discipline: create the image, grab into it, write it.

Staying card-based, the Hikrobot MV-GE1104 is a 4-port GigE frame grabber.

If your cameras take power over the network cable, the Hikrobot MV-GE2002P is a dual-port PoE NIC in a full height card.

Either card leaves the recording loop unchanged: the SDK copies each frame into your image, and the writer receives buffers that already hold pixels. Browse the frame grabbers category for the current range, filter by interface and ports in the accessories finder, and pick a current area scan camera from the camera finder. The configurator assembles camera, card and cables into one checked parts list.

Checks before you ship the recorder

• One image handle from create to write — the grab and the writer see the same buffer.
• Width and height read back non-zero after the first grab and equal the acquisition window.
• No resize call anywhere in the recording path.
• Image type is 8-bit gray or 32-bit RGB, matching the stream you opened.
• Line count of the acquisition window is even.
• Every write call's return code is logged, so the first rejection names itself.
• After close: file size within a few percent of frames × bytes per frame, and a mid-clip frame decodes with non-zero pixels.

If the arithmetic does not close for your window and frame rate, the contact page is the direct line to our applications team.