Pull Raw Pixel Data from an Image with ImageMagick stream

ImageMagick's stream writes raw pixel components straight to a file when a downstream tool just needs bytes, not a picture. The examples use stream-im6.q16 from ImageMagick 6.9.12-98 Q16, installed here as package imagemagick-6.q16 version 8:6.9.12.98+dfsg1-5.2ubuntu0.1~esm14.

Allow about fifteen minutes. You need a readable image and enough space for the output. These are ordinary user commands: no elevated privileges needed unless your input or destination directory is deliberately restricted. This guide reads image data and creates output files; it does not alter the source image.

1. Check the installed command

The package provides three names on this machine: stream, stream-im6 and the versioned stream-im6.q16. Check the version and use the versioned name in scripts, so an ImageMagick upgrade cannot silently change which command gets found first:

$ command -v stream-im6.q16
/usr/bin/stream-im6.q16
$ stream-im6.q16 -version
Version: ImageMagick 6.9.12-98 Q16 x86_64

The exact feature and delegate lines vary by build. The checkpoint that matters is that the command reports ImageMagick 6 and exits successfully. If it is missing, stop and install the distribution package through your normal package-management process rather than dropping a binary into a system directory.

2. Identify the source image before streaming it

Set a path to a real input file. Keep the placeholder quoted, then swap in your own path:

$ IMAGE='/path/to/input.png'
$ test -r "$IMAGE" && printf '%s\n' 'input is readable'
input is readable
$ stream-im6.q16 -identify "$IMAGE" /tmp/stream-identify.out
/path/to/input.png PNG 16x16 16x16+0+0 8-bit sRGB

-identify prints the format and characteristics while the command processes the image. The dimensions matter because a one-channel output normally contains one value per pixel in the selected area. Your format, dimensions and colour space will differ. If the read test fails, fix the path or permissions first; sudo is not a general remedy for a misspelt path.

3. Extract one channel to a new file

Use -map to choose pixel components. This writes the red component of every pixel as a one-byte-per-pixel raw stream for an 8-bit source:

$ stream-im6.q16 -map R -depth 8 "$IMAGE" /tmp/red-channel.raw
$ wc -c /tmp/red-channel.raw
256 /tmp/red-channel.raw

For a 16 by 16 image, 256 bytes is the expected size for one 8-bit component. For another image, calculate width * height and compare it against wc -c. R is one useful map, not a promise that every image stores red in the same colour model; use -channel, -colorspace or a different map when your workflow needs a particular interpretation.

To stream red, green and blue together, use -map RGB. A 16 by 16, 8-bit result should then contain 768 bytes:

$ stream-im6.q16 -map RGB -depth 8 "$IMAGE" /tmp/rgb.raw
$ wc -c /tmp/rgb.raw
768 /tmp/rgb.raw

These raw files carry no portable header. Keep the dimensions, depth and component order written down beside them, or use a format with a header when another program needs to discover those details itself.

4. Limit the work to a rectangular region

-extract selects a geometry in the form widthxheight+x+y. This example takes an 8 by 8 region starting four pixels from the left and top edges:

$ stream-im6.q16 -extract 8x8+4+4 -map R -depth 8 "$IMAGE" /tmp/red-crop.raw
$ wc -c /tmp/red-crop.raw
64 /tmp/red-crop.raw

Check the geometry against the source dimensions before running a large batch. The output size should be the selected width multiplied by the selected height for one 8-bit component. A crop changes which pixels are emitted; it does not resize the image or create a visual image file on its own.

For a quick boundary check, use file or the image tool that will consume the result. Do not open a raw stream in an image viewer without supplying its width, height, depth and component layout: a viewer that guesses wrong can make perfectly valid data look corrupted.

5. Use standard input and output deliberately

The manpage permits - as the input or output name. That is useful in a pipeline, but it also makes it easy to lose track of binary data. This example reads an image from standard input and writes the selected component to a named file:

$ cat "$IMAGE" | stream-im6.q16 -map R -depth 8 - /tmp/red-from-stdin.raw
$ test -s /tmp/red-from-stdin.raw && printf '%s\n' 'raw output is non-empty'
raw output is non-empty

Do not send the binary result to your terminal: redirect it to a file or pipe it to a program that explicitly accepts the format. A failed pipeline can also leave a partial destination, so check the command status and output size before treating the result as complete.

6. Avoid overwriting useful output

Shell redirection and ImageMagick output handling can both replace an existing destination. Work in a temporary name, verify it, then move it into place only once the replacement is correct:

$ stream-im6.q16 -map R -depth 8 "$IMAGE" /tmp/red-channel.raw.new
$ test -s /tmp/red-channel.raw.new
$ mv -- /tmp/red-channel.raw.new /path/to/verified/red-channel.raw

$ rm -- /tmp/red-channel.raw.new

Do not use rm on the source image as part of this workflow. There is no need for sudo to write a destination you own.

7. Diagnose the usual mismatches

• Command cannot open the input. Run ls -l -- "$IMAGE" and test -r "$IMAGE".
• Byte count is unexpected. Recheck the source dimensions, the extraction geometry, the map and the depth; a three-component stream is larger than a one-component stream, and a 16-bit depth is larger than an 8-bit one.
• Downstream reader says pixels are shifted or the image is the wrong size. The raw bytes may be valid but the reader's metadata is wrong; record the selected geometry, component map and depth alongside the output, or choose a self-describing format instead of assuming a file named .raw carries a header.

-quiet suppresses warnings, while -verbose prints more detail. Keep warnings enabled while diagnosing a new input. Use -limit when a batch job needs an explicit pixel-cache resource limit, and test that limit with representative files before deploying it: it is not a substitute for checking output integrity.