NAME

read_pix - create unit that reads image pixel values

PROTOTYPE

unitptr read_pix( int dx, int dy, int wdw, char *fmt, unitptr dest)

ARGUMENTS

int dx
width in pixels of image region read
int dy
height in pixels of image region read
int wdw
identifier of source window containing image region. A negative value -k can be used to specify the k-th (k=1,2,..) predecessor window managed by an NST-unit from a certain search range. The search range are the direct subunits of the read_pix's predecessor unit, if that unit is a container (i.e., a void_unit ). Otherwise, the search range are the predecessor units of read_pix that are on the same level, i.e., that share with read_pix the same host unit.
char *fmt
string to specify options
unitptr dest
host unit for newly created instance

RETURN VALUE:

unitptr u:
pointer to newly created unit

INTERFACE OF CREATED UNIT:

X_in[2]:
(input field 0) offset (in pixels) of lower left corner of image region from lower left corner of source window.
X_out[dx*dy]:
(packed output field) gray values of pixels read.
In addition, if wdw is a RGB-window AND fmt="COLOR"::
out_1[dx*dy]:
(packed output field 1) RED intensity
out_2[dx*dy]:
(packed output field 2) GREEN intensity
out_3[dx*dy]:
(packed output field 3) BLUE intensity

DESCRIPTION:

Creates a unit with one input field of two pins and one or four packed output field of dx*dy pins. The values of these pins are the gray values (range 0...255) of the pixels of a rectangular image region of width dx and height dy (in pixels). The option fmt="NOBLACK will translate all black pixels to white. For fmt="INVERT", gray values will be inverted (these options may be useful, e.g. to prepare image data for a postscript file).

Using Color:

If the window wdw is in RGB-mode, the gray values are the average of the three color intensities. The option fmt="COLOR" or fmt="RGB" will have the effect that three additional packed output fields for the R,G,B-intensities are created. If the window is in color map mode, only a single output field will be present, irrespective of the value of fmt. In this case, a proper translation of the image intensities into gray values requires that the window uses the NST-color map (which is the case for all NST-generated color-map mode windows). Pen colors will then be translated to gray values. If it is desired to preserve at least some color information, set fmt="COLOR". In this case, the predefined pen colors RED,GREEN,BLUE, YELLOW,MAGENTA and CYAN will be translated into negative intensity values such that they can be retranslated into the correct colors by a write_pix-unit, if this unit was created also for a color-map window and with fmt="COLOR".

Coordinates:

The gray and/or color value at pixel location (x,y) (.(0,0) = lower left corner of image region) is available at pin x + y*dx. The input values X_in[0] and X_in[1] at input field 0 specify the pixel coordinates of the lower left corner of the image region with respect to the lower left corner of the source window wid as origin. The created unit becomes a subunit of unit dest.

FILE

/local/homes/rhaschke/nst7/man/../o.linx86//../foldersrc/nst_pixel.c