read_sequenceread_sequenceReadSequenceReadSequenceread_sequence (Operator)


read_sequenceread_sequenceReadSequenceReadSequenceread_sequence — 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)

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

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)

def read_sequence(header_size: int, source_width: int, source_height: int, start_row: int, start_column: int, dest_width: int, dest_height: int, pixel_type: str, bit_order: str, byte_order: str, pad: str, index: int, file_name: str) -> HObject


The operator read_sequenceread_sequenceReadSequenceReadSequenceReadSequenceread_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 HeaderSizeHeaderSizeHeaderSizeHeaderSizeheaderSizeheader_size bytes) are skipped. The parameters SourceWidthSourceWidthSourceWidthSourceWidthsourceWidthsource_width and SourceHeightSourceHeightSourceHeightSourceHeightsourceHeightsource_height indicate the size of the filled image. DestWidthDestWidthDestWidthDestWidthdestWidthdest_width and DestHeightDestHeightDestHeightDestHeightdestHeightdest_height 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 StartRowStartRowStartRowStartRowstartRowstart_row and StartColumnStartColumnStartColumnStartColumnstartColumnstart_column.

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

'MSBFirst'"MSBFirst""MSBFirst""MSBFirst""MSBFirst""MSBFirst" (most significant bit first) or the inversion thereof ('LSBFirst'"LSBFirst""LSBFirst""LSBFirst""LSBFirst""LSBFirst") can be chosen for the bit order (BitOrderBitOrderBitOrderBitOrderbitOrderbit_order). The byte orders (ByteOrderByteOrderByteOrderByteOrderbyteOrderbyte_order) 'MSBFirst'"MSBFirst""MSBFirst""MSBFirst""MSBFirst""MSBFirst" (most significant byte first) or 'LSBFirst'"LSBFirst""LSBFirst""LSBFirst""LSBFirst""LSBFirst", respectively, are processed analogously. Finally an alignment (PadPadPadPadpadpad) can be set at the end of the line: 'byte'"byte""byte""byte""byte""byte", 'short'"short""short""short""short""short" or 'long'"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 IndexIndexIndexIndexindexindex.

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-like environment and can be set via the operator set_systemset_systemSetSystemSetSystemSetSystemset_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'"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 for the program examples). The environment variable HALCONROOT is used for the HALCON directory.


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


ImageImageImageImageimageimage (output_object)  image objectHImageHObjectHImageHobject * (byte / int2 / uint2 / int4)

Image read.

HeaderSizeHeaderSizeHeaderSizeHeaderSizeheaderSizeheader_size (input_control)  integer HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of bytes for file header.

Default value: 0

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

SourceWidthSourceWidthSourceWidthSourceWidthsourceWidthsource_width (input_control)  extent.x HTupleintHTupleHtuple (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 source_width

SourceHeightSourceHeightSourceHeightSourceHeightsourceHeightsource_height (input_control)  extent.y HTupleintHTupleHtuple (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 source_height

StartRowStartRowStartRowStartRowstartRowstart_row (input_control)  point.y HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Starting point of image area (line).

Default value: 0

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

Restriction: StartRow < SourceHeight

StartColumnStartColumnStartColumnStartColumnstartColumnstart_column (input_control)  point.x HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Starting point of image area (column).

Default value: 0

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

Restriction: StartColumn < SourceWidth

DestWidthDestWidthDestWidthDestWidthdestWidthdest_width (input_control)  extent.x HTupleintHTupleHtuple (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 dest_width

Restriction: DestWidth <= SourceWidth

DestHeightDestHeightDestHeightDestHeightdestHeightdest_height (input_control)  extent.y HTupleintHTupleHtuple (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 dest_height

Restriction: DestHeight <= SourceHeight

PixelTypePixelTypePixelTypePixelTypepixelTypepixel_type (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Type of pixel values.

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

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

BitOrderBitOrderBitOrderBitOrderbitOrderbit_order (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Sequence of bits within one byte.

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

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

ByteOrderByteOrderByteOrderByteOrderbyteOrderbyte_order (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Sequence of bytes within one 'short' unit.

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

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

PadPadPadPadpadpad (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Data units within one image line (alignment).

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

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

IndexIndexIndexIndexindexindex (input_control)  integer HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of images in the file.

Default value: 1

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

FileNameFileNameFileNameFileNamefileNamefile_name (input_control) HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Name of input file.


If the parameter values are correct the operator read_sequenceread_sequenceReadSequenceReadSequenceReadSequenceread_sequence returns the value TRUE. Otherwise an exception is raised.

Possible Successors

disp_imagedisp_imageDispImageDispImageDispImagedisp_image, count_channelscount_channelsCountChannelsCountChannelsCountChannelscount_channels, decompose3decompose3Decompose3Decompose3Decompose3decompose3, write_imagewrite_imageWriteImageWriteImageWriteImagewrite_image, rgb1_to_grayrgb1_to_grayRgb1ToGrayRgb1ToGrayRgb1ToGrayrgb1_to_gray



See also