ClassesClasses | | Operators

read_imageread_imageReadImageReadImage (Operator)

Name

read_imageread_imageReadImageReadImage — Read an image with different file formats.

Signature

read_image( : Image : FileName : )

Herror read_image(Hobject* Image, const char* FileName)

Herror T_read_image(Hobject* Image, const Htuple FileName)

void ReadImage(HObject* Image, const HTuple& FileName)

void HImage::HImage(const HTuple& FileName)

void HImage::HImage(const HString& FileName)

void HImage::HImage(const char* FileName)

void HImage::ReadImage(const HTuple& FileName)

void HImage::ReadImage(const HString& FileName)

void HImage::ReadImage(const char* FileName)

static void HOperatorSet.ReadImage(out HObject image, HTuple fileName)

public HImage(HTuple fileName)

public HImage(string fileName)

void HImage.ReadImage(HTuple fileName)

void HImage.ReadImage(string fileName)

Description

The operator read_imageread_imageReadImageReadImageReadImage reads the indicated image files from the background storage and generates the image. One or more file names can be passed in FileNameFileNameFileNameFileNamefileName. If more than one file name is passed, an image object tuple with the corresponding number of image objects is returned.

HALCON formats (HOBJ and IMA)

For images in the HALCON Iconic Object format (HOBJ), multiple images saved in one file are returned as a tuple of images. If regions or XLDs are contained within the file, an exception is raised. See write_objectwrite_objectWriteObjectWriteObjectWriteObject for more information about the HOBJ format.

All images files written by the operator write_imagewrite_imageWriteImageWriteImageWriteImage (format 'ima') have the extension '.ima'".ima"".ima"".ima"".ima". A description file can be available for every image in IMA format (same file name with extension '.exp'".exp"".exp"".exp"".exp"). The type of the pixel data ('byte'"byte""byte""byte""byte", 'int4'"int4""int4""int4""int4", 'real'"real""real""real""real") can also be taken from the description file. If the description file is not available, the type 'byte'"byte""byte""byte""byte" is used by default as well as a default data size ('height'"height""height""height""height" x 'width'"width""width""width""width") that can be queried via get_systemget_systemGetSystemGetSystemGetSystem. If the data size of the '.ima'".ima"".ima"".ima"".ima" file and the default data size are not equal, an exception is raised.

Other formats

Besides the HALCON formats, TIFF, GIF, BMP, JPEG, JPEG-2000, JPEG-XR, PNG, PCX, SUN-Raster, PGM, PPM, PBM, and XWD files can also be read. The gray values of PBM images are set at the values 0 and 255. The file formats are either recognized by the extension (if indicated) or because of the internal structure of the files. If the extension is indicated the image can be found faster. If no extension is indicated, files with an extension are preferred to files without extension. In case of PGM, PPM, and PBM the corresponding extension (e.g., 'pgm'"pgm""pgm""pgm""pgm") or the general value 'pnm'"pnm""pnm""pnm""pnm" can be used. In case of TIFF 'tiff'"tiff""tiff""tiff""tiff" and 'tif'"tif""tif""tif""tif" are accepted. In case of JPEG-XR 'jxr', 'wdp', 'wmp' and 'hdp' are accepted. In case of JPEG-2000 only 'jp2'"jp2""jp2""jp2""jp2" is accepted. In case of colored images an image with three color channels is created, the red channel being stored in the first, the green channel in the second and the blue channel in the third component (channel number).

For the image formats TIFF, PNG, JPEG-XR, and JPEG-2000, binary alpha channels are interpreted as domains. For TIFF files, additionally binary SubIFDs with PhotometricInterpretation = TransparencyMask are interpreted as domains. Otherwise, the domain of the generated image object (= all pixels of the matrix) is chosen maximal.

For TIFF images, multipage TIFF files are returned as image object tuples.

Images of type 'int8' can be read on 64 bit systems only. Furthermore, only the IMA and the TIFF format support this image type.

Image files are searched in the current directory and in the image directory of HALCON (determined by the environment variable). 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.

Attention

If CMYK or YCCK JPEG/JPEG-XR files are read, HALCON assumes that these files follow the Adobe Photoshop convention that the CMYK channels are stored inverted, i.e., 0 represents 100% ink coverage, rather than 0% ink as one would expect. The images are converted to RGB images using this convention. If the JPEG file does not follow this convention, but stores the CMYK channels in the usual fashion, invert_imageinvert_imageInvertImageInvertImageInvertImage must be called after reading the image.

If PNG images that contain an alpha channel are read, the alpha channel is returned as the second or fourth channel of the output image, unless the alpha channel contains exactly two different gray values, in which case a one or three channel image with a reduced domain is returned, in which the points in the domain correspond to the points with the higher gray value in the alpha channel.

Execution Information

Parameters

ImageImageImageImageimage (output_object)  image(-array) objectHImageHImageHobject * (byte / direction / cyclic / int1 / complex / int2 / uint2 / vector_field / int4 / int8 / real)

Read image.

FileNameFileNameFileNameFileNamefileName (input_control)  filename.read(-array) HTupleHTupleHtuple (string) (string) (HString) (char*)

Name of the image to be read.

Default value: 'printer_chip/printer_chip_01' "printer_chip/printer_chip_01" "printer_chip/printer_chip_01" "printer_chip/printer_chip_01" "printer_chip/printer_chip_01"

Suggested values: 'fabrik'"fabrik""fabrik""fabrik""fabrik", 'fuse'"fuse""fuse""fuse""fuse", 'mreut'"mreut""mreut""mreut""mreut", 'multiple_dies_01'"multiple_dies_01""multiple_dies_01""multiple_dies_01""multiple_dies_01", 'particle'"particle""particle""particle""particle", 'patras'"patras""patras""patras""patras", 'printer_chip/printer_chip_01'"printer_chip/printer_chip_01""printer_chip/printer_chip_01""printer_chip/printer_chip_01""printer_chip/printer_chip_01", 'rings_and_nuts'"rings_and_nuts""rings_and_nuts""rings_and_nuts""rings_and_nuts", 'tooth_rim'"tooth_rim""tooth_rim""tooth_rim""tooth_rim"

File extension: .hobj, .ima, .tif, .tiff, .gif, .bmp, .jpg, .jpeg, .jp2, .jxr, .png, .pcx, .ras, .xwd, .pbm, .pnm, .pgm, .ppm

Example (HDevelop)

* Reading an image:
  read_image(Image,'mreut')

* Reading 3 images into an image array:
  read_image(Images,['ic0','ic1','ic2'])

* Setting of search path for images on '/mnt/images' and '/home/images':
  set_system('image_dir','/mnt/images:/home/images')

Example (C)

/* Reading an image: */
  read_image(&Image,"mreut") ;

/* Reading 3 images into an image array: */
  Htuple Files ;
  create_tuple(&Files,3) ;
  set_s(Files,"ic0",0) ;
  set_s(Files,"ic1",1) ;
  set_s(Files,"ic2",2) ;
  T_read_image(&Images,Files) ;

/* Setting of search path for images on '/mnt/images' and '/home/images': */
  set_system("image_dir","/mnt/images:/home/images") ;

Example (HDevelop)

* Reading an image:
  read_image(Image,'mreut')

* Reading 3 images into an image array:
  read_image(Images,['ic0','ic1','ic2'])

* Setting of search path for images on '/mnt/images' and '/home/images':
  set_system('image_dir','/mnt/images:/home/images')

Example (HDevelop)

* Reading an image:
  read_image(Image,'mreut')

* Reading 3 images into an image array:
  read_image(Images,['ic0','ic1','ic2'])

* Setting of search path for images on '/mnt/images' and '/home/images':
  set_system('image_dir','/mnt/images:/home/images')

Example (HDevelop)

* Reading an image:
  read_image(Image,'mreut')

* Reading 3 images into an image array:
  read_image(Images,['ic0','ic1','ic2'])

* Setting of search path for images on '/mnt/images' and '/home/images':
  set_system('image_dir','/mnt/images:/home/images')

Result

If the parameters are correct the operator read_imageread_imageReadImageReadImageReadImage returns the value 2 (H_MSG_TRUE). Otherwise an exception is raised.

Possible Successors

disp_imagedisp_imageDispImageDispImageDispImage, thresholdthresholdThresholdThresholdThreshold, regiongrowingregiongrowingRegiongrowingRegiongrowingRegiongrowing, count_channelscount_channelsCountChannelsCountChannelsCountChannels, decompose3decompose3Decompose3Decompose3Decompose3, class_ndim_normclass_ndim_normClassNdimNormClassNdimNormClassNdimNorm, gauss_filtergauss_filterGaussFilterGaussFilterGaussFilter, fill_interlacefill_interlaceFillInterlaceFillInterlaceFillInterlace, zoom_image_sizezoom_image_sizeZoomImageSizeZoomImageSizeZoomImageSize, zoom_image_factorzoom_image_factorZoomImageFactorZoomImageFactorZoomImageFactor, crop_partcrop_partCropPartCropPartCropPart, write_imagewrite_imageWriteImageWriteImageWriteImage, rgb1_to_grayrgb1_to_grayRgb1ToGrayRgb1ToGrayRgb1ToGray

Alternatives

read_sequenceread_sequenceReadSequenceReadSequenceReadSequence

See also

set_systemset_systemSetSystemSetSystemSetSystem, write_imagewrite_imageWriteImageWriteImageWriteImage

Module

Foundation


ClassesClasses | | Operators