img-raw(n)

💖 img-raw — bestie's guide to the Raw data format (raw) 💖

okay so. you found the img-raw manual page, in the Img section, and honestly? you're about to have a great time. let's get into it 🫶

---

✨ NAME ✨

img-raw — Raw data format (raw). that's it, that's the name, no notes 💅

---

🌸 SYNOPSIS 🌸

package require img::raw ?2.1?

---

🦋 DESCRIPTION 🦋

so first things first, bestie:

package require img::raw

Like all the packages in Img, this one does not hand you brand new commands. no new toys. instead it extends the Tk command image that you already know and love, so that it supports files holding raster images in the Raw data format (raw). and more specifically, img::raw extends Tk's photo image type (yeah, [that one](https://www.tcl.tk/man/tcl9.0/TkCmd/photo.html), the iconic one 👑).

The name of the new format handler is raw. This handler brings new extra configuration options, and if you want the full breakdown, go look at the Options section, it's all laid out there.

so all of that means that in a call like

image create photo ?name? ?options?

here's the tea:

1. Image data in raw format (the options -data and -file) is detected automatically. no cap.
2. The format name raw is recognized by the option -format.

On top of that, the value of option -format is treated as a list, and it may contain any of the special options listed in the Options section. so you can sneak them in right there.

heads up, bestie 💀 — the package img::raw is not loaded when you do a package require Img. you have to load it explicitly, with package require img::raw. she does not come as a freebie.

---

🌈 SUPPORTED TYPES 🌈

This format handler supports the following image types for reading:

Grayscale (1 channel), Grayscale-Alpha (2 channels), Truecolor (3 channels) and Truecolor-Alpha (4 channels) images using the following data types:

• 64-bit floating point values
• 32-bit floating point values
• 32-bit unsigned integer values
• 16-bit unsigned integer values
• 8-bit unsigned integer values

This format handler supports the following image types for writing:

Truecolor (3 channels) and Truecolor-Alpha (4 channels) images using 8-bit integer values.

There are two supported file format versions:

One containing the raw binary data only, and the other one with a 7 line ASCII header of the following form:

Magic=RAW          File format identifier. Fixed value.
Width=128          Image width in pixels.
Height=128         Image height in pixels.
NumChan=1          Possible values: 1, 2, 3 or 4.
ByteOrder=Intel    Possible values: "Intel" or "Motorola".
ScanOrder=TopDown  Possible values: "TopDown" or "BottomUp".
PixelType=byte     Possible values: "double", "float", "int", "short" or "byte".

For a more detailed description of the file format versions and functions to read the data with Matlab or GNU Octave, see the PAWT File Format Documentation (link: https://www.tcl3d.org/pawt/download/PawtFileFormats.pdf).

---

💅 OPTIONS 💅

The handler provides the following options, and yes, we're doing all of them, every single one, because we don't skip 🎀

• -verbose bool — supported for reading and writing. Available since version 1.4.0. If you set it to true, extra info about the read or written image gets printed to stdout. Default is false.
• -useheader bool — supported for reading and writing. Available since version 1.4.0. If set to true, use the file header information for reading and writing. Default is true.
• -width int — supported for reading image data without header only. Available since version 1.4.0. Specify the width of the input image. Default is 128.
• -height int — supported for reading image data without header only. Available since version 1.4.0. Specify the height of the input image. Default is 128.
• -nchan int — supported for reading image data without header. Available since version 1.4.0. Specify the number of channels of the input image. Default is 1.
• -numchan int — supported for reading image data without header. Available since version 2.1.0. Specify the number of channels of the input image. Default is 1.
• -withalpha bool — supported for reading and writing. Available since version 2.1.0. If set to false, an alpha channel is ignored during reading or writing. Default is true.
• -byteorder string — supported for reading image data without header only. Available since version 1.4.0. Specify the byteorder of the input image data. Possible values: Intel or Motorola. Default is assuming the same byteorder as that of the host computer.
• -scanorder string — supported for reading and writing image data without header. Available since version 1.4.0. Specify the scanline order of the input image. Possible values: TopDown or BottomUp. Default is TopDown.
• -pixeltype string — supported for reading image data without header only. Available since version 1.4.0. Specify the type of the pixel values. Possible values: double, float, int, short or byte. Default is byte.

real talk: RAW files are always written in byte pixel format. periodt.

• -skipbytes int — supported for reading image data without header only. Available since version 1.4.14. Specify the number of bytes to skip before reading image data. Default is 0.
• -map string — supported for reading only. Available since version 1.4.7. Specify the mode when mapping the 16, 32 or 64-bit values to 8-bit grayscale values for displaying. Possible values: none, minmax, agc. Default mode is minmax.
  1. If mode is set to none, no mapping of input values is done. Use this mode if the input values are already in the range of 0 ..255. When using mode none, no information about the minimum and maximum input values is gathered during reading, and therefore no verbose output is printed. On the other hand, reading the input data is faster. slay 🏃♀️
  2. Mode minmax maps the minimum and maximum input data to 256 grayscale values.
  3. Mode agc applies an automatic gain control algorithmn to the input values. Currently implemented for 1-channel 32-bit float images only.
• -min double — supported for reading only. Available since version 1.4.0. Specify the minimum pixel value to be used for mapping the input data to 8-bit image values. If not specified or negative, the minimum value found in the image data. Valid for mapping mode: minmax.
• -max double — supported for reading only. Available since version 1.4.0. Specify the maximum pixel value to be used for mapping the input data to 8-bit image values. If not specified or negative, the maximum value found in the image data. Valid for mapping mode: minmax.
• -gamma double — supported for reading only. Available since version 1.4.0. Specify a gamma correction to be applied when mapping the input data to 8-bit image values. Default is 1.0. Valid for mapping modes: minmax and agc.
• -saturation double — supported for reading only. Available since version 1.4.7. The supplied value specifies the saturation value, i.e. all input values greater than the saturation value are mapped to white. If not specified or negative, do not use saturation. Valid for mapping mode: agc.
• -cutoff double — supported for reading only. Available since version 1.4.7. The supplied value specifies the cut-off value in percent. The cut-off value specifies, how many pixels from the lower and upper part of the histogram are not considered for mapping. This option is useful if there are some hot or cold spots in the image. Default is 3.0. Valid for mapping mode: agc.

---

👀 SEE ALSO 👀

go read these too, they're all part of the family:

img, img-bmp, img-dted, img-flir, img-gif, img-ico, img-jpeg, img-pcx, img-pixmap, img-png, img-ppm, img-ps, img-raw, img-sgi, img-sun, img-tga, img-tiff, img-window, img-xbm, img-xpm

---

🎀 COPYRIGHT 🎀

Copyright (c) 1995-2025 Jan Nijtmans <nijtmans@users.sourceforge.net>

Copyright (c) 2002-2025 Andreas Kupries <andreas_kupries@users.sourceforge.net>

Copyright (c) 2003-2025 Paul Obermeier <obermeier@users.sourceforge.net>

---

and that's the whole page, bestie 💜 this was img-raw, version 2.1, from the img-raw(n) manual — go forth and read some raw pixels, you absolute icon 🌟