Hand-eye calibration build errors: resolve dependency mismatches

A hand-eye calibration GUI can fail to compile even when its dependencies appear to be installed. Missing class methods and rejected function calls often indicate that the compiler sees a different API from the one the GUI source expects. This troubleshooting procedure helps you identify the selected headers, distinguish an incompatible dependency from an incorrect call, and rebuild a documented compatible software set. Start with build evidence rather than changing calibration settings or replacing camera hardware.

1. Confirm that the failure happens during compilation

First identify the failing stage. Compilation, linking, plugin discovery, and calibration execution use different evidence and need different fixes.

A missing member reported by the compiler is not initially a plugin search-path problem. The compiler has found a class declaration, but that declaration does not provide the requested member in the current configuration.

If compilation succeeds and the application subsequently rejects the plugin, use the plugin loading diagnostic procedure. For unresolved symbols after object files compile, follow the separate C++ linking dependency checks.

2. Read the first meaningful compiler diagnostic

Save the complete build log before editing anything. Parallel builds interleave messages, so the last visible error may only report that an earlier compilation failed.

For an existing CMake build directory named build, a single-worker verbose build can make the sequence easier to follow:

cmake --build build --verbose --parallel 1

If your project uses a workspace build frontend, use its documented equivalent. Do not substitute a direct CMake invocation when the workspace requires additional configuration steps.

For the earliest failing translation unit, record:

• The source file and failing expression.
• The class or namespace involved.
• The actual argument types at the call site.
• Every candidate declaration printed by the compiler.
• The header path associated with those declarations.

A missing method and an incompatible overload can be two symptoms of the same dependency mismatch. However, neither proves which release you need.

Do not replace a missing method with the compiler's similarly named suggestion without checking its documented behavior. A method that publishes visualization data is not necessarily equivalent to one that removes it.

Likewise, an overload accepting a filename does not automatically replace one accepting an in-memory mesh. Making the code compile through an arbitrary conversion may change the intended behavior.

3. Prove which headers the compiler actually reads

Installing or compiling a dependency does not prove that the GUI uses it. Include-path order, cached package discovery, and previously sourced workspace environments can select another copy.

Inspect the exact compiler command for the failing file. Focus on ordinary include directories, system include directories, preprocessor definitions, and the order in which they appear.

Where supported by the selected generator, enable CMAKE_EXPORT_COMPILE_COMMANDS during configuration. The resulting compile_commands.json records compilation commands for individual translation units. It is useful evidence, but it does not itself list every resolved header.

Use your compiler's documented include-tracing option, or inspect its generated dependency records, to identify the header actually opened. A top-level include can also pull an older dependency through a nested include.

Record both the configured package location and the resolved header path. They answer different questions:

• Package discovery identifies which package configuration the build selected.
• Include tracing identifies which declarations the compiler actually consumed.
• Link commands identify which binary libraries the target will use later.

If the expected declaration is present in the selected file, inspect conditional compilation and generated configuration headers. A declaration may be excluded by a feature flag even when the release is otherwise correct.

4. Establish a documented compatibility baseline

Choose a supported software combination before choosing a repair. Use the project's release documentation and dependency documentation obtained through official project or distributor channels.

Record the operating-system release, middleware distribution, compiler, GUI source revision, dependency revisions, and build options. Prefer immutable release tags or commit identifiers over a moving development branch.

A simple example shows why random upgrades become expensive. Suppose you have 2 possible GUI revisions and 3 visualization dependency revisions:

These are candidate environments, not validated combinations. A documented release set reduces the search space before you spend time rebuilding.

Create a small manifest with an expected revision and an observed location for each dependency. Include transitive dependencies that provide the failing class, not just the package named directly by the GUI.

If the GUI expects an API introduced after your installed release, the legitimate choices are to adopt the documented newer dependency set or use a GUI revision supporting the installed set. If an API was removed, the direction may be reversed.

The software integration tradeoffs guide explains why release support and maintenance ownership matter alongside initial functionality.

5. Resolve mixed source and installed dependencies

Consider a hypothetical build with these observations:

The presence of a newly compiled library does not repair the selected header. Conversely, selecting a new header does not establish binary compatibility with an older library.

Work through the repair in a controlled order:

1. Preserve the current evidence. Save logs, revision identifiers, configuration options, and local source changes.
2. Select the documented dependency set. Decide which dependencies come from installed packages and which come from source.
3. Start a clean shell environment. Initialize only the intended base installation and required workspace overlays, following their documentation.
4. Check discovery results. Confirm that package configuration paths point to the selected dependency locations.
5. Create fresh generated build output. Use the workspace tool's documented clean or reconfigure procedure without deleting source files or calibration data.
6. Build in dependency order. Complete the changed dependency and its required dependents before rebuilding the GUI.
7. Inspect the new commands and paths. Confirm the compiler now reads the intended declarations and the linker selects corresponding libraries.

Do not remove system packages blindly to force discovery. Other applications may depend on them. An isolated, documented workspace can provide a safer diagnostic baseline than changing a production installation.

6. Decide between dependency alignment and source adaptation

Dependency alignment is usually the first choice when the GUI belongs to a documented release set. It preserves the API contract expected by that source revision.

Source adaptation becomes reasonable when you intentionally maintain a port to another supported environment. Treat it as an engineering change, not a compiler-error suppression exercise.

For each changed call, verify:

• The accepted argument types and ownership rules.
• Coordinate-frame and transformation conventions.
• Visualization identifiers and replacement behavior.
• Whether data is published immediately or queued.
• Clearing, lifetime, and cleanup behavior.
• Return values and failure handling.

A cast that silences a type error is not evidence of equivalent semantics. Nor is commenting out a visualization call necessarily harmless: it may remove feedback used to recognize a wrong frame or stale target pose.

After an intentional adaptation, add a focused test for the changed behavior. Keep the patch separate from dependency updates so another maintainer can understand why it exists.

When a compatible release set is available, avoid mixing a broad upgrade with unrelated source edits. Changing one variable at a time makes failures easier to attribute.

7. Verify compilation before testing calibration behavior

Use a staged acceptance sequence rather than treating a successful build as the final result.

First, rebuild the previously failing target and confirm that the original missing-member or overload diagnostics are gone. Then build the complete GUI package and run the project's available tests.

Next, launch the application in a controlled environment and verify plugin discovery, initialization, and shutdown. If it fails at this stage, return to the runtime loading procedure rather than continuing to edit compile-time calls.

Check visualization with known data. Confirm that transforms appear in the intended frame, updates replace the expected markers, and clearing operations remove stale displays. A GUI that opens but displays old transforms is not ready for calibration work.

Only then test image acquisition and calibration data handling. Preserve existing parameters using the calibration parameter storage checks. If the software changes affect frame definitions or pose interpretation, follow the calibration recovery procedure before production use.

8. Keep camera selection separate from the API repair

Changing a camera will not add a missing C++ method to a visualization dependency. Reproduce the build failure without connected hardware where the project's documented build process permits it.

Camera selection matters later, when validating acquisition and deployment. Compare area scan cameras using the camera finder only after defining the application's imaging requirements.

The LS-CMR-0053 provides a GigE option for acquisition planning. Confirm driver and application compatibility separately from the calibration GUI build.

The LS-CMR-0166 provides a USB3 option. Its interface does not establish compatibility with a particular calibration package or operating environment.

If deployment calls for a dedicated vision box, review vision controllers against the required camera connections and supported software environment. Do not infer software support from connector availability alone.

Use the camera configuration starting point when defining a new acquisition setup. Keep that hardware decision separate from the dependency manifest used to reproduce the software build.

9. Prevent recurrence and prepare a useful support handoff

Before accepting the repaired environment, complete this checklist:

• Pin revisions: record exact source identifiers and installed package versions so another machine can reproduce the result.
• Record provenance: save selected package configuration, header, and library locations rather than only package names.
• Capture build options: preserve feature flags, compiler selection, and the workspace initialization sequence.
• Retest from fresh generated output: confirm that success does not depend on stale objects or cached discovery results.
• Separate acceptance stages: record compilation, linking, plugin loading, acquisition, and calibration verification independently.
• Preserve rollback material: retain the previous known-working software manifest and calibration records under your change-control process.

If the failure remains, prepare a concise support bundle containing the first diagnostic, relevant candidate declarations, selected header path, failing compiler command, and revision manifest. Remove credentials, proprietary images, and unrelated machine information before sharing it.

For help planning acquisition hardware or a supported integration path, contact the applications team with that evidence and your required camera interface. A reproducible dependency record is more useful than a screenshot of the final build failure.