You are here: Start » Function Reference » Computer Vision » Datacodes » ReadSingleDataMatrixCode_Deprecated

ReadSingleDataMatrixCode_Deprecated

Header:	AVL.h
Namespace:	avl
Module:	Datacodes

Detects and recognizes one Data Matrix code.

Syntax

void avl::ReadSingleDataMatrixCode_Deprecated
(
	avl::ReadDataCodes_State& ioState,
	const avl::Image& inImage,
	atl::Optional<const avl::Rectangle2D&> inRoi,
	atl::Optional<const avl::CoordinateSystem2D&> inRoiAlignment,
	const avl::DatacodeParams& inCodeParams,
	const avl::DatacodeDetectionParams& inDetectionParams,
	bool inComputeScores,
	atl::Conditional<avl::DataCode>& outDataMatrixCode,
	atl::Array<avl::Path>& outCandidates,
	atl::Optional<avl::Rectangle2D&> outAlignedRoi = atl::NIL
)

Parameters

Name	Type	Default	Description
ioState	ReadDataCodes_State&		Object used to maintain state of the function.
inImage	const Image&		Input image
inRoi	Optional<const Rectangle2D&>	NIL	Region of interest
inRoiAlignment	Optional<const CoordinateSystem2D&>	NIL	Coordinate system for the region of interest
inCodeParams	const DatacodeParams&		Specification of codes that can be detected
inDetectionParams	const DatacodeDetectionParams&		Parameters of the code detection algorithm
inComputeScores	bool		Enables computing of confidence scores (slower)
outDataMatrixCode	Conditional<DataCode>&		A code that has been correctly detected and decoded
outCandidates	Array<Path>&		Diagnostic information about detection results
outAlignedRoi	Optional<Rectangle2D&>	NIL	Input ROI after transformation (in the image coordinates)

Optional Outputs

The computation of following outputs can be switched off by passing value atl::NIL to these parameters: outAlignedRoi.

Description

This filter detects and recognizes one data matrix code in an image. If there are more codes the tool may find any of them.

Supported code types: ECC 200 and ECC 000-140.

Groups of parameters

For optimal efficiency, the tool may require careful setting of parameters. Most of the parameters are divided into two groups:

inCodeParams – parameters concerning the code; these can be set precisely according to what codes we expect to read
inDetectionParams – parameters concerning the algorithm; these may require some experimentation, as different approaches may work best in different scenarios

Detection methods

The most important setting is the selection of the code detection algorithm, inDetectionParams.DetectionMethod. The tool offers three options:

	Quiet Zone	Finder Pattern	Finder Edges
Where it looks?
How it works?	Looks for the blank space surrounding the code. In theory, it should be empty for a width of at least one module.	Looks for the blob of the L-shaped pattern. In theory, it should be continuous and not connected with anything outside of the code.	Looks for the edges of the L-shaped pattern. It uses a robust line segment detector internally.
When to use it?	This method is good even for partially broken Finder Pattern, but it will fail if there is any contamination in the Quiet Zone.	This method may deal with some contamination in the Quiet Zone, but it will fail if the Finder Pattern itself is not good.	This method works well even if Quiet Zone is contaminated and Finder Pattern is not perfect, but may be confused by additional lines appearing near the code.

Pyramid

The tool tries to detect codes at different scale levels. It investigates images at different resolutions, starting with the lowest resolution. If it finds a sufficient number of codes at one level, it may skip looking further, thus achieving shorter execution time. If there are no codes in the input image, it will always scan all the levels, resulting in the highest execution time.

NOTE: If you experience instable execution times, for example, switching between 10 ms and 20 ms, it may indicate that for some images the tool finds a code at a higher level, while for some others it has to process the higher resolution too. For that reason, we also recommend testing time performance on the ReadMultipleDataCodes tool, with inMaxCodeCount=1000 and inAllowMultipleScales=True. This will assure that no early exit happens, and the execution time will be the maximum of what we may expect with the given settings.

Finder Tradeoff ("FinderEdges" only)

When using the "FinderEdges" method, you should be aware that there is a tradeoff between the ability of the tool to detect rugged (uneven, noised, or dot printed) edges and the ability to detect low contrast edges (or ones neighboring with a very narrow Quite Zone). The default setting is "Balanced". However, if you expect the edges of your code to be relatively straight and clean, but less strong, you may want to change it to "Sensitive". On the other hand, if the edges of the code are highly jagged or the surrounding is noisy, it may be better to choose "Robust". You may also set it to "Auto" and it will test several possibilities at the cost of much higher execution time.

Use "Sensitive"	Use "Balanced"	Use "Robust"

Distortions

The tool can deal with various types of code deformations. There are three possible settings, as demonstrated below. Please be aware that when we make the algorithm more robust to distortions, we make it less robust to broken code patterns. For this reason, we should stay with lower settings whenever possible.

Use "Low"	Use "Medium"	Use "High"


Each side is represented with a single line segment.	Each side is represented with a 3-segment line.	Each side is exactly traced with a polyline.

Damaged codes and other difficulties

By using appropriate inCodeParams settings, you can also find codes that are partially damaged. See the below table for some of the most common cases.