region_to

Herror ::region_to_bin ( Hobject Region, Hobject *BinImage, const HTuple &ForegroundGray, const HTuple &BackgroundGray, const HTuple &Width, const HTuple &Height ) HImage HRegion::RegionToBin ( const HTuple &ForegroundGray, const HTuple &BackgroundGray, const HTuple &Width, const HTuple &Height ) const HImage HRegionArray::RegionToBin ( const HTuple &ForegroundGray, const HTuple &BackgroundGray, const HTuple &Width, const HTuple &Height ) const

Convert a region into a binary byte-image.

::region_to_bin converts the input region given in Region into a byte-image and assigns a gray value of ForegroundGray to all pixels in the region. If the input region is larger than the generated image, it is clipped at the image borders. The background is set to BackgroundGray.

Parameters

`Region` (input_object)	region(-array) `->` Hobject: HRegion(Array)
Regions to be converted.

`BinImage` (output_object)	image `->` Hobject : HImage* ( byte )
Result image of dimension Width Height containing the converted regions.*

`ForegroundGray` (input_control)	integer `->` HTuple.long
Gray value in which the regions are displayed.
Default value: 255
Suggested values: 0, 1, 50, 100, 128, 150, 200, 254, 255
Typical range of values: `0 <= ForegroundGray <= 255` (lin)
Recommended increment: 1

`BackgroundGray` (input_control)	integer `->` HTuple.long
Gray value in which the background is displayed.
Default value: 0
Suggested values: 0, 1, 50, 100, 128, 150, 200, 254, 255
Typical range of values: `0 <= BackgroundGray <= 255` (lin)
Recommended increment: 1

`Width` (input_control)	extent.x `->` HTuple.long
Width of the image to be generated.
Default value: 512
Suggested values: 256, 512, 1024
Typical range of values: `1 <= Width <= 1024` (lin)
Minimum increment: 1
Recommended increment: 16
Restriction: `Width >= 1`

`Height` (input_control)	extent.y `->` HTuple.long
Height of the image to be generated.
Default value: 512
Suggested values: 256, 512, 1024
Typical range of values: `1 <= Height <= 1024` (lin)
Minimum increment: 1
Recommended increment: 16
Restriction: `Height >= 1`

Complexity

O(2*Height*Width).

Result

::region_to_bin always returns H_MSG_TRUE. The behavior in case of empty input (no regions given) can be set via ::set_system('no_object_result',<Result>) and the behavior in case of an empty input region via ::set_system('empty_region_result',<Result>). If necessary, an exception handling is raised.

Possible Predecessors

::threshold, ::connection, ::regiongrowing, ::pouring

Possible Successors

::get_grayval

Alternatives

::region_to_label, ::paint_region, ::set_grayval

See also

::gen_image_proto, ::paint_gray

Module

Image / region / XLD management