Read images.
The operator read_sequence reads unformatted image data, from a file and returns a ``suitable'' image. The image data must be filled consecutively pixel by pixel and line by line.
Any file headers (with the length HeaderSize bytes) are skipped. The parameters SourceWidth and SourceHeight indicate the size of the filled image. DestWidth and DestHeight indicate the size of the image. In the simplest case these parameters are the same. However, areas can also be read. The upper left corner of the required image area can be determined via StartRow and StartColumn.
The pixel types 'bit', 'byte', 'short' (16 bits, unsigned), 'signed_short' (16 bits, signed), 'long' (32 bits, signed), 'swapped_long' (32 bits, with swapped segments), and 'real' (32 bit floating point numbers) are supported. Furthermore, the operator read_sequence enables the extraction of components of a RBG image, if a triple of three bytes (in the sequence ``red'', ``green'', ``blue'') was filed in the image file. For the red component the pixel type 'r_byte' must be chosen, and correspondingly for the green and blue components 'g_byte' or 'b_byte', respectively.
'MSBFirst' (most significant bit first) or the inversion thereof ('LSBFirst') can be chosen for the bit order (BitOrder). The byte orders (ByteOrder) 'MSBFirst' (most significant byte first) or 'LSBFirst', respectively, are processed analogously. Finally an alignment (Pad) can be set at the end of the line: 'byte', 'short' or 'long'. If a whole image sequence is stored in the file a single image (beginning at Index 1) can be chosen via the parameter Index.
Image files are searched in the current directory (determined by the environment variable) and in the image directory of HALCON . The image directory of HALCON is preset at '.' and '/usr/local/halcon/images' in a UNIX environment and can be set via the operator set_system. More than one image directory can be indicated. This is done by separating the individual directories by a colon.
Furthermore the search path can be set via the environment variable HALCONIMAGES (same structure as 'image_dir'). Example:
setenv HALCONIMAGES "/usr/images:/usr/local/halcon/images"
HALCON also searches images in the subdirectory "images" (Images for the program examples). The environment variable HALCONROOT is used for the HALCON directory.
If files of pixel type 'real' are read and the byte order is chosen incorrectly (i.e., differently from the byte order in which the data is stored in the file) program error and even crashes because of floating point exceptions may result.
|
Image (output_object) |
image -> object : byte / int2 / uint2 / int4 |
| Image read. | |
|
HeaderSize (input_control) |
integer -> integer |
| Number of bytes for file header. | |
| Default value: 0 | |
| Typical range of values: 0 <= HeaderSize | |
|
SourceWidth (input_control) |
extent.x -> integer |
| Number of image columns of the filed image. | |
| Default value: 512 | |
| Typical range of values: 1 <= SourceWidth | |
|
SourceHeight (input_control) |
extent.y -> integer |
| Number of image lines of the filed image. | |
| Default value: 512 | |
| Typical range of values: 1 <= SourceHeight | |
|
StartRow (input_control) |
point.y -> integer |
| Starting point of image area (line). | |
| Default value: 0 | |
| Typical range of values: 0 <= StartRow | |
| Restriction: StartRow < SourceHeight | |
|
StartColumn (input_control) |
point.x -> integer |
| Starting point of image area (column). | |
| Default value: 0 | |
| Typical range of values: 0 <= StartColumn | |
| Restriction: StartColumn < SourceWidth | |
|
DestWidth (input_control) |
extent.x -> integer |
| Number of image columns of output image. | |
| Default value: 512 | |
| Typical range of values: 1 <= DestWidth | |
| Restriction: DestWidth <= SourceWidth | |
|
DestHeight (input_control) |
extent.y -> integer |
| Number of image lines of output image. | |
| Default value: 512 | |
| Typical range of values: 1 <= DestHeight | |
| Restriction: DestHeight <= SourceHeight | |
|
PixelType (input_control) |
string -> string |
| Type of pixel values. | |
| Default value: 'byte' | |
| List of values: 'bit', 'byte', 'r_byte', 'g_byte', 'b_byte', 'short', 'signed_short', 'long', 'swapped_long' | |
|
BitOrder (input_control) |
string -> string |
| Sequence of bits within one byte. | |
| Default value: 'MSBFirst' | |
| List of values: 'MSBFirst', 'LSBFirst' | |
|
ByteOrder (input_control) |
string -> string |
| Sequence of bytes within one 'short' unit. | |
| Default value: 'MSBFirst' | |
| List of values: 'MSBFirst', 'LSBFirst' | |
|
Pad (input_control) |
string -> string |
| Data units within one image line (alignment). | |
| Default value: 'byte' | |
| List of values: 'byte', 'short', 'long' | |
|
Index (input_control) |
integer -> integer |
| Number of images in the file. | |
| Default value: 1 | |
| Typical range of values: 1 <= Index | |
|
FileName (input_control) |
filename -> string |
| Name of input file. | |
If the parameter values are correct the operator read_sequence returns the value 2 (H_MSG_TRUE). If the file cannot be opened 5 (H_MSG_FAIL) is returned. Otherwise an exception handling is raised.
read_sequence is processed under mutual exclusion against itself and without parallelization.
disp_image, count_channels, decompose3, write_image, rgb1_to_gray
Image / region / XLD management
