Barcode detection coordinate indexing: prevent overlay errors

A barcode payload can decode correctly while the next operation fails when drawing its location. The decoder, coordinate parser and annotation routine are separate stages, so changing exposure or enabling more symbologies may solve the wrong problem. This troubleshooting workflow helps you identify the failing operation, validate returned geometry and build overlay inputs with matching dimensions. It applies to saved-image tests and production applications that receive barcode results from a camera or reader.

Separate decoding from annotation first

Start with the complete exception text and the exact operation that raised it. An error reported after a successful decode does not automatically mean that the barcode location is wrong. The application may have indexed an empty array, assumed an unsupported geometry layout or constructed an invalid drawing argument.

Split the processing chain into independently observable stages:

1. Acquire or load the image and assign an image identifier.
2. Run detection and decoding.
3. Record the returned status, payload, format and geometry metadata.
4. Validate the geometry without drawing anything.
5. Construct and render the overlay.
6. Display or transmit the annotated result.

Temporarily disable stages after decoding. If the same image still produces its expected payload, preserve that result while investigating annotation separately. Do not clear a valid decoded value merely because a diagnostic graphic failed.

Conversely, detection of a candidate region does not necessarily mean decoding succeeded. Some interfaces expose candidate locations even when no payload is available. Keep the documented decode status authoritative.

For failures involving missing symbols or search coverage, use the multiple-code image and search diagnostic workflow. The workflow here begins with the returned result and asks whether your application consumes it correctly.

Check emptiness and the coordinate contract before indexing

Never access the first point until you have established that a point exists. Checking the payload alone is insufficient: a result interface may provide text without geometry, or your application may accidentally combine outputs from different calls.

Inspect the documented return type before making assumptions. Geometry might be a numeric matrix, a collection containing one matrix per symbol, a rectangle or a structure with named fields. These are not interchangeable representations.

Record at least these details during diagnosis:

• Image identifier and image dimensions.
• Decode status and number of symbol results.
• Geometry container type and dimensions.
• Numeric type and whether coordinates are finite.
• Coordinate origin, units and reference image.
• The operation that failed and its complete error text.

If the interface documents a point matrix with shape N × 2, each row contains one point and the columns contain its horizontal and vertical coordinates. Validate that contract before extracting either column.

An empty result can have different dimensions depending on the interface. Handle the documented empty representation before enforcing the nonempty matrix shape. Do not assume every empty result will be a numeric matrix with zero rows and two columns.

Also reject nonfinite coordinates before rendering. A numeric array can have the expected dimensions while still containing invalid values.

Count point rows, not the largest array dimension

A common failure occurs when an application uses an array-length function to determine how many radius values to create. In environments where length means the largest dimension, that is not necessarily the number of points.

Consider a documented point matrix containing a single point:

points = [[120, 75]]
shape(points) = 1 × 2
point count = number of rows = 1
largest dimension = 2

Suppose the circle renderer expects one row per circle in the form [x, y, radius]. A radius column must therefore have the same row count as the point matrix.

With one point, the correct construction is:

points:   [[120, 75]]       shape 1 × 2
radii:    [[6]]             shape 1 × 1
circles:  [[120, 75, 6]]    shape 1 × 3

Using the largest dimension instead would produce a radius column with two rows. Horizontal concatenation would then attempt to combine a 1 × 2 matrix with a 2 × 1 matrix. The row counts disagree, so construction fails before the renderer receives anything.

With four points, the same incorrect method may happen to work because the largest dimension is also the row count. That explains why an annotation routine can pass one test and fail another without any decoder change.

The following is interface-neutral pseudocode, not a library-specific implementation:

geometry = geometry_for_selected_symbol(result)

if geometry_is_empty(geometry):
    record_annotation_status("no geometry")
else:
    points = extract_documented_point_matrix(geometry)
    require_two_coordinate_columns(points)
    require_finite_values(points)

    point_count = row_count(points)
    radii = constant_column(point_count, marker_radius)
    circle_rows = concatenate_columns(points, radii)

    draw_circles(annotation_copy, circle_rows)

Adapt the extraction and drawing operations to the documented interfaces you actually use. The invariant is the matching row count, not the names of the functions.

Match each overlay to its required geometry

Different overlay primitives require different argument layouts. Even when every primitive uses coordinates, you cannot pass the same matrix to each one unchanged.

The table shows common layouts. Confirm the exact contract in your renderer's documentation before implementing them.

Do not assume returned barcode points describe a rectangular boundary. Depending on the interface, they may represent endpoints, corners or another documented location convention. A polygon around them is meaningful only when their semantics support it.

If you draw a horizontal reference line through a returned point, that line is a visualization aid. It is not automatically the decoder's scan path or the barcode's physical centerline.

Coordinate conventions deserve a separate check. Image arrays are often indexed as row then column, while graphical points are often expressed as horizontal then vertical position. That distinction can swap otherwise valid values.

For zero-based pixel-center coordinates, valid centers normally satisfy 0 ≤ x < width and 0 ≤ y < height. For one-based pixel-center coordinates, the corresponding limits are 1 ≤ x ≤ width and 1 ≤ y ≤ height. Use the convention documented for your interface, particularly when it returns continuous boundary coordinates rather than pixel centers.

An otherwise valid circle may extend beyond an image edge because its radius exceeds the available margin. Decide whether your renderer should clip it or report it. Do not silently clamp malformed coordinates and then treat the altered overlay as evidence of a correct location.

Diagnose the symptom with a controlled test

Use a saved image and fixed parameters while investigating. Keep the original image unchanged and draw onto a separate copy. This prevents annotations from entering a later decoding pass and changing the evidence.

For a crop beginning at horizontal offset 100 and vertical offset 40, a crop-relative point (20, 30) maps to full-image position (120, 70). The arithmetic is 100 + 20 = 120 and 40 + 30 = 70. Apply this translation only when the returned coordinates are actually crop-relative.

If the isolated decoding stage also fails, investigate image quality separately. The barcode preprocessing guide for rotation, blur and glare addresses that branch without confusing it with array construction errors.

Check the result interface before replacing hardware

An indexing exception alone is not evidence that a different camera or reader is required. First determine which component produces the payload and which component supplies geometry.

With fixed code readers, confirm the documented output fields and whether location data is available through your chosen interface. The LS-CRD-0028 fixed code reader is a catalog option to evaluate when the task calls for a dedicated reader. Confirm its application interface against your requirements rather than assuming a particular coordinate format.

For smart cameras, establish whether annotations are generated on the device or in your application. The LS-SMC-0063 smart camera is an option to review for that architecture. The catalog information alone does not establish a specific barcode tool or geometry return contract.

With area scan cameras, the host application's decoder generally defines the result representation rather than the camera's image transport. The LS-CMR-0053 area scan camera is an acquisition option to review separately from decoder selection.

Use the camera and reader finder to compare acquisition requirements only after you have identified an actual hardware limitation. Before ordering, confirm image coverage, motion requirements, interface compatibility and access to the result fields your application needs.

Verify the fix with a small regression checklist

Test the result consumer independently from the decoder by supplying controlled geometry fixtures. Include invalid inputs deliberately and check that they produce a clear diagnostic rather than an unhandled exception.

• No symbol result: do not access a first point or reuse a previous overlay.
• Decoded payload without geometry: retain the payload and report annotation as unavailable when the interface permits this state.
• One point: construct exactly one marker row.
• Two and four points: preserve the documented order and create matching parameter rows.
• Multiple symbols: keep each payload associated with its own geometry.
• Malformed geometry: reject unexpected dimensions and nonfinite coordinates before drawing.
• Image edges: confirm the intended clipping behavior without moving the reported point.
• Crop or resize: verify coordinates against the exact image being displayed.
• Repeated acquisition: confirm that payload, geometry and displayed image carry the same identifier.

For moving applications, conveyor image association and duplicate handling helps separate repeated observations from stale result reuse. If processing triggers interface updates, nonrecursive barcode event handling addresses that separate integration risk.

The fix is verified when valid geometry renders correctly, empty results follow an intentional branch and malformed results produce useful diagnostics. Decoding and annotation should have separate statuses throughout.

If you need help selecting an acquisition or reader interface, use application support with the complete exception, failing operation, coordinate dimensions and a representative image. Those details make the next step specific instead of turning an overlay fault into an unnecessary hardware change.