poImg User Manual

For detailed information regarding the available commands, see the reference manual.

User manual contents

Introduction

A poImg image can contain up to 13 different channels. The following table shows the available channel types.

Value	C enumeration	Tcl variable or name	Description
0	FF_ImgChanTypeBrightness	BRIGHTNESS	Brightness for grayscale images
1	FF_ImgChanTypeRed	RED	Red value for color images
2	FF_ImgChanTypeGreen	GREEN	Green value for color images
3	FF_ImgChanTypeBlue	BLUE	Blue value for color images
4	FF_ImgChanTypeMatte	MATTE	Global transparency
5	FF_ImgChanTypeRedMatte	REDMATTE	Transparency for red channel
6	FF_ImgChanTypeGreenMatte	GREENMATTE	Transparency for green channel
7	FF_ImgChanTypeBlueMatte	BLUEMATTE	Transparency for blue channel
8	FF_ImgChanTypeHoriSnr	HNORMAL	Direction of face normal, horizontal
9	FF_ImgChanTypeVertSnr	VNORMAL	Direction of face normal, vertical
10	FF_ImgChanTypeDepth	DEPTH	Distance from the eye point
11	FF_ImgChanTypeTemperature	TEMPERATURE	Temperature
12	FF_ImgChanTypeRadiance	RADIANCE	Radiance

Each channel can contain values in either UByte or Float format. The following table shows the available channel formats.

Value	C enumeration	Tcl variable or name	Description
0	FF_ImgFmtTypeNone	NONE	None, channel does not exist
1	FF_ImgFmtTypeUByte	UBYTE	Unsigned 8-bit integers
2	FF_ImgFmtTypeFloat	FLOAT	32-bit floating point numbers

Note:
Channels in Float format are clipped to the range [0.0, 1.0] with the exception of the TEMPERATURE and RADIANCE channels.

The image processing functionality is state-machine based like OpenGL. The poImg state consists of the following members:

Channel format (see function SetFormat)
Draw mask (see function SetDrawMask)
Draw color (see function SetDrawColor)
Draw mode (see function SetDrawMode)

The state can be pushed onto and popped from a stack of state settings using functions PushState and PopState .

Tcl usage

To use poImg issue the following command in a tclsh: package require poImg

The following commands are then added to the global namespace:

poImageState
This command has subcommands to set or get state settings.

poImage
This command has subcommands to create a new poImg image. The image can either be a new blank image (NewImage), read from an image file (NewImageFromFile) or copied from a Tk photo image (NewImageFromPhoto).

After creation of a poImg image, a command for that image is created in the global namespace similar to the Tk image create photo command. The command identifiers are named starting with poImage1 and the number in the name is incremented with each image creation.

Note:
Each command and subcommand supports a "?" as parameter to print usage information.

In addition to these core commands, which are implemented in C and wrapped for Tcl, an utility libary poImgUtil is supported. This library contains several higher level procedures for easier usage of the image processing functionality.

Supported image formats

Native support of the following image file formats: TGA, SGI, RAW, POI.
Support of other image file formats via the Img extension.

The functions for reading and writing support options identical to the options of the Img extension.

See the Img reference manual for a description of the options of the TGA, SGI and RAW formats.

The POI image file format is the native file format of the poImg extension and supports storing all supported image channels and formats.

See the documenation of the NewImageFromFile and WriteImage commands for further information.

The following figure shows an overview of the available options:

poImg
raw		tga		sgi		poi
read	write	read	write	read	write	read	write
-verbose	-verbose	-verbose	-verbose	-verbose	-verbose	-verbose	-verbose
-withalpha	-withalpha	-withalpha	-witalpha	-withalpha	-withalpha	-withalpha	-withalpha
			-compression		-compression		-compression
-scanorder	-scanorder		-scanorder
-useheader	-useheader
-width
-height
-numchan
-byteorder	-byteorder
-pixeltype
-skipbytes
-map
-min
-max
-gamma
-saturation
-cutoff

The advanced mapping options (marked in red-italic) of the Img extension are not supported with poImg, as poImg supports floating point images.

Build poImg

poImg is based on the Tcl Extension Architecture (TEA) and can be build using the standard configure / make process.

In addition to the standard TEA configuration options, the following package specific options are supported:

Option	Default value	Description
--enable-threads	on	If set to off, poImg switches off support for threading.
--enable-tkphotos	on	If set to off, poImg switches off support for Tk photos. No need for the Tk library anymore.
--enable-macros	on	If set to off, switch several access functions from macros to functions. Use for debugging.
--enable-memdebug	off	If set to on, print detailed information regarding leaked memory. Use for debugging.

Test suite

The poImg library contains two Tcl based test suites:

A standard tcltest based test suite, which mainly tests error cases.
A visual test suite, where generated images are compared against reference images.

The tcltest based test suite is located in subdirectory tests and is executed as follows:
tclsh all.tcl

The visual test suite is located in subdirectory tests/visualtests and is executed as follows:
tclsh RunTest.tcl all

Note:
The visual test suite is run by default in single-threaded mode.
To run all visual tests with threading enabled, edit file testui.tcl and set the number of threads from 0 to the wished number:
poImageState SetNumThreads 0

Known issues

There are 1 pixel differences in some of the reference images when comparing images generated on x86_64 architecture with images generated on arm64 or RiscV.