img-raw3tk

Usage

Overview

package require img::raw

Like all packages of Img it does not provide new commands, but extends the existing Tk command image, so that it supports files containing raster images in the Raw data format (raw). More specifically img::raw extends Tk's photo [https://www.tcl.tk/man/tcl9.0/TkCmd/photo.html] image type.

The name of the new format handler is raw. This handler provides new additional configuration options. See section Options for more detailed explanations.

All of the above means that in a call like image create photo ?name? ?options?

In addition the value of option -format is treated as a list and may contain any of the special options listed in section Options.

The package img::raw is not loaded when doing a package require Img, but must be loaded explicitly via package require img::raw.

Supported types

This format handler supports the following image types:

Grayscale (1 channel) and truecolor (3 channels) images using the following data types

There are two supported file format versions:

One containing the raw binary data only, the other 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 or 3.
     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 [https://www.tcl3d.org/pawt/download/PawtFileFormats.pdf].

Options

The handler provides the following options:

-verbose bool

This option is supported for reading and writing. Available since version 1.4.0.

If set to true, additional information about the read or written image is printed to stdout. Default is false.

-useheader bool

This option is 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

This option is 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

This option is 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

This option is supported for reading and writing image data without header. Available since version 1.4.0.

Specify the number of channels of the input image. Default is 1.

-byteorder string

This option is 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

This option is 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

This option is 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.

-skipbytes int

This option is 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

This option is 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

This option is 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

This option is 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

This option is 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

This option is 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

This option is 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.