Herror ::read_sequence (
    Hobject *Image,
    const HTuple &HeaderSize,
    const HTuple &SourceWidth,
    const HTuple &SourceHeight,
    const HTuple &StartRow,
    const HTuple &StartColumn,
    const HTuple &DestWidth,
    const HTuple &DestHeight,
    const HTuple &PixelType,
    const HTuple &BitOrder,
    const HTuple &ByteOrder,
    const HTuple &Pad,
    const HTuple &Index,
    const HTuple &FileName
)
HImage HImage::ReadSequence (
    const HTuple &HeaderSize,
    const HTuple &SourceWidth,
    const HTuple &SourceHeight,
    const HTuple &StartRow,
    const HTuple &StartColumn,
    const HTuple &DestWidth,
    const HTuple &DestHeight,
    const HTuple &PixelType,
    const HTuple &BitOrder,
    const HTuple &ByteOrder,
    const HTuple &Pad,
    const HTuple &Index,
    const HTuple &FileName
)

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) and 'swapped_long' (32 bits, with swapped segments) 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.

Parameters

Image (output_object)
 image -> Hobject * : HImage
Image read.

HeaderSize (input_control)
 integer -> HTuple.long
Number of bytes for file header.
Default value: 0
Typical range of values: 0 <= HeaderSize

SourceWidth (input_control)
 extent.x -> HTuple.long
Number of image columns of the filed image.
Default value: 512
Typical range of values: 1 <= SourceWidth

SourceHeight (input_control)
 extent.y -> HTuple.long
Number of image lines of the filed image.
Default value: 512
Typical range of values: 1 <= SourceHeight

StartRow (input_control)
 point.y -> HTuple.long
Starting point of image area (line).
Default value: 0
Typical range of values: 0 <= StartRow
Restriction: StartRow < SourceHeight

StartColumn (input_control)
 point.x -> HTuple.long
Starting point of image area (column).
Default value: 0
Typical range of values: 0 <= StartColumn
Restriction: StartColumn < SourceWidth

DestWidth (input_control)
 extent.x -> HTuple.long
Number of image columns of output image.
Default value: 512
Typical range of values: 1 <= DestWidth
Restriction: DestWidth <= SourceWidth

DestHeight (input_control)
 extent.y -> HTuple.long
Number of image lines of output image.
Default value: 512
Typical range of values: 1 <= DestHeight
Restriction: DestHeight <= SourceHeight

PixelType (input_control)
 string -> HTuple.char *
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 -> HTuple.char *
Sequence of bits within one byte.
Default value: 'MSBFirst'
List of values: 'MSBFirst', 'LSBFirst'

ByteOrder (input_control)
 string -> HTuple.char *
Sequence of bytes within one 'short' unit.
Default value: 'MSBFirst'
List of values: 'MSBFirst', 'LSBFirst'

Pad (input_control)
 string -> HTuple.char *
Data units within one image line (alignment).
Default value: 'byte'
List of values: 'byte', 'short', 'long'

Index (input_control)
 integer -> HTuple.long
Number of images in the file.
Default value: 1
Typical range of values: 1 <= Index

FileName (input_control)
 filename -> HTuple.char *
Name of input file.

Result

If the parameter values are correct the operator ::read_sequence returns the value H_MSG_TRUE. If the file cannot be opened H_MSG_FAIL is returned. Otherwise an exception handling is raised.

Possible Successors

::disp_image, ::count_channels, ::decompose3, ::write_image, ::rgb1_to_gray

Alternatives

::read_image

See also

::read_image

Module

Image / region / XLD management

Copyright © 1996-2002 MVTec Software GmbH