ClassesClasses | | Operators

read_sequenceread_sequenceReadSequenceReadSequence (Operator)


read_sequenceread_sequenceReadSequenceReadSequence — Read images.


read_sequence( : Image : HeaderSize, SourceWidth, SourceHeight, StartRow, StartColumn, DestWidth, DestHeight, PixelType, BitOrder, ByteOrder, Pad, Index, FileName : )

Herror read_sequence(Hobject* Image, const Hlong HeaderSize, const Hlong SourceWidth, const Hlong SourceHeight, const Hlong StartRow, const Hlong StartColumn, const Hlong DestWidth, const Hlong DestHeight, const char* PixelType, const char* BitOrder, const char* ByteOrder, const char* Pad, const Hlong Index, const char* FileName)

Herror T_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)

void ReadSequence(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)

void HImage::ReadSequence(Hlong HeaderSize, Hlong SourceWidth, Hlong SourceHeight, Hlong StartRow, Hlong StartColumn, Hlong DestWidth, Hlong DestHeight, const HString& PixelType, const HString& BitOrder, const HString& ByteOrder, const HString& Pad, Hlong Index, const HString& FileName)

void HImage::ReadSequence(Hlong HeaderSize, Hlong SourceWidth, Hlong SourceHeight, Hlong StartRow, Hlong StartColumn, Hlong DestWidth, Hlong DestHeight, const char* PixelType, const char* BitOrder, const char* ByteOrder, const char* Pad, Hlong Index, const char* FileName)

static void HOperatorSet.ReadSequence(out HObject image, HTuple headerSize, HTuple sourceWidth, HTuple sourceHeight, HTuple startRow, HTuple startColumn, HTuple destWidth, HTuple destHeight, HTuple pixelType, HTuple bitOrder, HTuple byteOrder, HTuple pad, HTuple index, HTuple fileName)

void HImage.ReadSequence(int headerSize, int sourceWidth, int sourceHeight, int startRow, int startColumn, int destWidth, int destHeight, string pixelType, string bitOrder, string byteOrder, string pad, int index, string fileName)


The operator read_sequenceread_sequenceReadSequenceReadSequenceReadSequence 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 HeaderSizeHeaderSizeHeaderSizeHeaderSizeheaderSize bytes) are skipped. The parameters SourceWidthSourceWidthSourceWidthSourceWidthsourceWidth and SourceHeightSourceHeightSourceHeightSourceHeightsourceHeight indicate the size of the filled image. DestWidthDestWidthDestWidthDestWidthdestWidth and DestHeightDestHeightDestHeightDestHeightdestHeight 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 StartRowStartRowStartRowStartRowstartRow and StartColumnStartColumnStartColumnStartColumnstartColumn.

The pixel types 'bit'"bit""bit""bit""bit", 'byte'"byte""byte""byte""byte", 'short'"short""short""short""short" (16 bits, unsigned), 'signed_short'"signed_short""signed_short""signed_short""signed_short" (16 bits, signed), 'long'"long""long""long""long" (32 bits, signed), 'swapped_long'"swapped_long""swapped_long""swapped_long""swapped_long" (32 bits, with swapped segments), and 'real'"real""real""real""real" (32 bit floating point numbers) are supported. Furthermore, the operator read_sequenceread_sequenceReadSequenceReadSequenceReadSequence 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'"r_byte""r_byte""r_byte""r_byte" must be chosen, and correspondingly for the green and blue components 'g_byte'"g_byte""g_byte""g_byte""g_byte" or 'b_byte'"b_byte""b_byte""b_byte""b_byte", respectively.

'MSBFirst'"MSBFirst""MSBFirst""MSBFirst""MSBFirst" (most significant bit first) or the inversion thereof ('LSBFirst'"LSBFirst""LSBFirst""LSBFirst""LSBFirst") can be chosen for the bit order (BitOrderBitOrderBitOrderBitOrderbitOrder). The byte orders (ByteOrderByteOrderByteOrderByteOrderbyteOrder) 'MSBFirst'"MSBFirst""MSBFirst""MSBFirst""MSBFirst" (most significant byte first) or 'LSBFirst'"LSBFirst""LSBFirst""LSBFirst""LSBFirst", respectively, are processed analogously. Finally an alignment (PadPadPadPadpad) can be set at the end of the line: 'byte'"byte""byte""byte""byte", 'short'"short""short""short""short" or 'long'"long""long""long""long". If a whole image sequence is stored in the file a single image (beginning at Index 1) can be chosen via the parameter IndexIndexIndexIndexindex.

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'"/usr/local/halcon/images""/usr/local/halcon/images""/usr/local/halcon/images""/usr/local/halcon/images" in a Unix-like environment and can be set via the operator set_systemset_systemSetSystemSetSystemSetSystem. 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'"image_dir""image_dir""image_dir""image_dir"). Example:

     setenv HALCONIMAGES "/usr/images:/usr/local/halcon/images"

HALCON also searches images in the subdirectory '"`images"'""`images""""`images""""`images""""`images"" (Images for the program examples). The environment variable HALCONROOT is used for the HALCON directory.


If files of pixel type 'real'"real""real""real""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.

Execution Information


ImageImageImageImageimage (output_object)  image objectHImageHImageHobject * (byte / int2 / uint2 / int4)

Image read.

HeaderSizeHeaderSizeHeaderSizeHeaderSizeheaderSize (input_control)  integer HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of bytes for file header.

Default value: 0

Typical range of values: 0 ≤ HeaderSize HeaderSize HeaderSize HeaderSize headerSize

SourceWidthSourceWidthSourceWidthSourceWidthsourceWidth (input_control)  extent.x HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of image columns of the filed image.

Default value: 512

Typical range of values: 1 ≤ SourceWidth SourceWidth SourceWidth SourceWidth sourceWidth

SourceHeightSourceHeightSourceHeightSourceHeightsourceHeight (input_control)  extent.y HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of image lines of the filed image.

Default value: 512

Typical range of values: 1 ≤ SourceHeight SourceHeight SourceHeight SourceHeight sourceHeight

StartRowStartRowStartRowStartRowstartRow (input_control)  point.y HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Starting point of image area (line).

Default value: 0

Typical range of values: 0 ≤ StartRow StartRow StartRow StartRow startRow

Restriction: StartRow < SourceHeight

StartColumnStartColumnStartColumnStartColumnstartColumn (input_control)  point.x HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Starting point of image area (column).

Default value: 0

Typical range of values: 0 ≤ StartColumn StartColumn StartColumn StartColumn startColumn

Restriction: StartColumn < SourceWidth

DestWidthDestWidthDestWidthDestWidthdestWidth (input_control)  extent.x HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of image columns of output image.

Default value: 512

Typical range of values: 1 ≤ DestWidth DestWidth DestWidth DestWidth destWidth

Restriction: DestWidth <= SourceWidth

DestHeightDestHeightDestHeightDestHeightdestHeight (input_control)  extent.y HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of image lines of output image.

Default value: 512

Typical range of values: 1 ≤ DestHeight DestHeight DestHeight DestHeight destHeight

Restriction: DestHeight <= SourceHeight

PixelTypePixelTypePixelTypePixelTypepixelType (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Type of pixel values.

Default value: 'byte' "byte" "byte" "byte" "byte"

List of values: 'b_byte'"b_byte""b_byte""b_byte""b_byte", 'bit'"bit""bit""bit""bit", 'byte'"byte""byte""byte""byte", 'g_byte'"g_byte""g_byte""g_byte""g_byte", 'long'"long""long""long""long", 'r_byte'"r_byte""r_byte""r_byte""r_byte", 'real'"real""real""real""real", 'short'"short""short""short""short", 'signed_short'"signed_short""signed_short""signed_short""signed_short", 'swapped_long'"swapped_long""swapped_long""swapped_long""swapped_long"

BitOrderBitOrderBitOrderBitOrderbitOrder (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Sequence of bits within one byte.

Default value: 'MSBFirst' "MSBFirst" "MSBFirst" "MSBFirst" "MSBFirst"

List of values: 'LSBFirst'"LSBFirst""LSBFirst""LSBFirst""LSBFirst", 'MSBFirst'"MSBFirst""MSBFirst""MSBFirst""MSBFirst"

ByteOrderByteOrderByteOrderByteOrderbyteOrder (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Sequence of bytes within one 'short' unit.

Default value: 'MSBFirst' "MSBFirst" "MSBFirst" "MSBFirst" "MSBFirst"

List of values: 'LSBFirst'"LSBFirst""LSBFirst""LSBFirst""LSBFirst", 'MSBFirst'"MSBFirst""MSBFirst""MSBFirst""MSBFirst"

PadPadPadPadpad (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Data units within one image line (alignment).

Default value: 'byte' "byte" "byte" "byte" "byte"

List of values: 'byte'"byte""byte""byte""byte", 'long'"long""long""long""long", 'short'"short""short""short""short"

IndexIndexIndexIndexindex (input_control)  integer HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of images in the file.

Default value: 1

Typical range of values: 1 ≤ Index Index Index Index index (lin)

FileNameFileNameFileNameFileNamefileName (input_control) HTupleHTupleHtuple (string) (string) (HString) (char*)

Name of input file.


If the parameter values are correct the operator read_sequenceread_sequenceReadSequenceReadSequenceReadSequence returns the value 2 (H_MSG_TRUE). Otherwise an exception is raised.

Possible Successors

disp_imagedisp_imageDispImageDispImageDispImage, count_channelscount_channelsCountChannelsCountChannelsCountChannels, decompose3decompose3Decompose3Decompose3Decompose3, write_imagewrite_imageWriteImageWriteImageWriteImage, rgb1_to_grayrgb1_to_grayRgb1ToGrayRgb1ToGrayRgb1ToGray



See also




ClassesClasses | | Operators