img-raw(3tk)

💖 NAME 💖

img-raw — the Raw data format handler (the format's called raw, iykyk) 🌈

---

✨ SYNOPSIS ✨

package require img::raw ?2.1?

---

🦋 DESCRIPTION 🦋

package require img::raw

Okay so here's the tea, bestie: just like every package in Img, this one does not hand you any shiny new commands. Nope. What it does is extend the Tk command image that you already know and love, so that it can handle files stuffed with raster images in the Raw data format (raw). And more specifically — drumroll — img::raw extends Tk's photo image type, the one documented over at https://www.tcl.tk/man/tcl9.0/TkCmd/photo.html 📸

The name of the new format handler is raw. This handler brings new extra configuration options to the party. Peep the Options section for the full breakdown, no crumbs left behind.

All of the above means that when you make a call like image create photo ?name? ?options?:

1. Image data in raw format (that's the options -data and -file) gets detected automatically. She just knows. 🔮
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. Periodt.

Heads up bestie: the package img::raw is not loaded when you do a package require Img. Nope. You have to load it explicitly with package require img::raw. Don't forget or you'll be sitting there like 😭

---

👑 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. That's it, that's the list 💅

There are two supported file format versions, and they're giving very different vibes:

One contains the raw binary data only. The other comes 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, go read the PAWT File Format Documentation at https://www.tcl3d.org/pawt/download/PawtFileFormats.pdf 🧚

---

🎀 OPTIONS 🎀

The handler provides the following options:

• -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.

RAW files are always written in byte pixel format. Always. No exceptions, bestie.

• -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. ⚡
  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 🌸

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 — the whole girl gang, go say hi 🫶

---

💜 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>

---

That's the whole page, bestie — this is the img-raw manual from Img, version 2.1, and honestly? She ate. 💅✨ Go read some raw pixels, you've got this. 🦋