Camera SDK missing OpenCV headers: causes, tests and fixes

A camera SDK build that configures cleanly can still stop dead at fatal error: opencv/cv.h: No such file or directory — or the same message for opencv2/core.hpp. The SDK's dependency chain and your OpenCV installation disagree, in one of four ways. This guide gives the test and the fix for each cause in order of probability: an OpenCV generation mismatch, missing development files, an include root one directory too deep, and optional modules pulled into the build scope. The commands target a Linux CMake build (Ubuntu 20.04, CMake 3.16); on MSVC swap -I for /I and the logic holds. Get SDK source, firmware and manuals from the manufacturer or its distributors, and install the OpenCV series the release notes name before editing a single line.

Read the first fatal error, not the summary line

The first fatal error names the cause; everything after it is fallout. Record four facts before changing anything: the failing source file, the header it requested, the target it belongs to, and the full compile command. cmake --build build-check --verbose prints every compile line (CMake 3.14 and later accept --verbose on --build).

Place the failure in one of four buckets:

Start with the generation mismatch: OpenCV 4 has been the default on mainstream Linux distributions since Ubuntu 20.04 shipped OpenCV 4.2, so it is the first cause to rule out.

Cause 1: the SDK wants OpenCV 3, the machine has OpenCV 4

OpenCV 4.0, released in November 2018, removed the C API headers opencv/cv.h, opencv/highgui.h, opencv/cvaux.h and opencv/ml.h; the C++ headers stayed under opencv2/. A source file from an older SDK that asks for opencv/cv.h fails on every complete OpenCV 4 installation.

Test it: pkg-config --modversion opencv4 answers 4.2.0 on Ubuntu 20.04's libopencv-dev. An answer in the 4.x range plus a request for a legacy header is the whole diagnosis.

Fix it on the supported path: take the SDK branch that targets OpenCV 4, or build OpenCV 3.4 in its own prefix such as /opt/opencv-3.4 and point OpenCV_DIR at it for that SDK alone. Do not rewrite the includes. The C++ replacements behind opencv2/opencv.hpp change types and calls, so the error moves from the include line to missing declarations a few lines further down.

Decision: new code goes on OpenCV 4; a legacy SDK stays on 3.4 in its own prefix until its OpenCV 4 branch arrives.

Cause 2: runtime installed, development files absent

The packaged camera tool runs, which tells you libopencv_core.so is present. Runtime and development files are separate packages: headers and OpenCVConfig.cmake arrive with libopencv-dev, not with the runtime libraries.

Test it: dpkg -l | grep libopencv-dev returns nothing on a runtime-only machine.

Fix it: sudo apt install libopencv-dev. On Ubuntu 20.04 that installs OpenCV 4.2 headers at /usr/include/opencv4. Keep one major.minor per build tree: headers from 4.5 against a 4.2 runtime fail at link or load.

Cause 3: the include root is one level off

Editors resolve headers through their own index; the compiler sees only the -I, -isystem or /I arguments of its target. That is why completion works while the build fails. Worked example, Ubuntu 20.04: the source requests opencv2/core.hpp, and the file sits at /usr/include/opencv4/opencv2/core.hpp.

The include root is the directory after -I; the requested header is the path inside the #include line. The root here is /usr/include/opencv4. Passing -I/usr/include/opencv4/opencv2 instead sends the compiler to /usr/include/opencv4/opencv2/opencv2/core.hpp, one directory too deep — and a wrong root fails exactly like a missing installation.

Fix it at package level, never in source. OpenCV_DIR names the directory that contains OpenCVConfig.cmake: /usr/lib/x86_64-linux-gnu/cmake/opencv4 for Ubuntu 20.04's package, the build tree for a source build. Configure in one line:

cmake -S . -B build-clean -DCMAKE_BUILD_TYPE=Release -DOpenCV_DIR=/usr/lib/x86_64-linux-gnu/cmake/opencv4

Then link against the imported targets (OpenCV::core, OpenCV::imgproc) so the include directories travel with the library into every target that needs them.

Cause 4: modules you never needed are in scope

Vision SDKs bundle acquisition with optional processing. A failure inside a viewer or analytics target while the acquisition sample compiles means the scope is wrong, not the installation.

Take an SDK with 8 library targets: 2 for acquisition (discovery, buffering, format conversion) and 6 for optional processing. The component switch named in the release notes cuts the build to the acquisition pair:

Here 8 counts the SDK's libraries, 6 the optional processing targets and 2 the acquisition targets that remain. Compile time drops, and the 2 remaining targets state their own dependencies, which shrinks the OpenCV question to what acquisition needs.

Frames need no OpenCV at all. A GigE Vision camera streams through the transport layer and exposes its settings as a GenICam feature tree, with names like ExposureTime and TriggerSource standardized by the GenICam standard features naming convention. OpenCV enters at undistortion, color conversion and display — example code, not acquisition.

Isolate in five steps:

1. Configure the core acquisition library.
2. Build its smallest sample.
3. Confirm the camera enumerates and frames arrive.
4. Add one processing component per rebuild.
5. Record the first target that fails.

Reconfigure in a clean build directory

CMake caches discovery results in CMakeCache.txt. Install OpenCV somewhere new, change compiler or toolchain, and the old cache answers with stale paths — the same missing-header error, now for a different reason.

Keep the failed log, then from the verified source root run cmake -S . -B build-clean followed by cmake --build build-clean --verbose. Diff the OpenCV_DIR and compiler lines between the old and new caches; a difference there is the whole story. Never copy the old cache into the clean directory.

Accept the build, then accept the frames

A green build is half the acceptance. Run the checks in order:

• The previously failing source compiles with no edited includes.
• The sample links and starts without missing-library messages.
• The camera enumerates on its interface.
• The first frame arrives within one frame period: the LS-CMR-0053 streams at 9 fps, so the first frame is due about 0.11 s after acquisition starts (1 / 9 fps is about 0.11 s).

Record the SDK release, OpenCV version, operating system, compiler and configure arguments together. That record, not a screenshot of the last message, is what reproduces the build on the next machine.

When frames time out after a clean build, the include path is no longer the problem: camera SDK build mismatch and frame-timeout diagnosis takes it from there.

Hardware with a supported acquisition path

With the build clean, choose hardware whose SDK meets your platform. A GigE Vision camera answers to any compliant transport stack, so the software question reduces to the interface library you just built. Browse area scan cameras or the camera finder and match the sensor to the task. The LS-CMR-0053 is a 12 MP GigE area scan camera with a 1/1.7" rolling-shutter sensor, C-mount and 9 fps — a plain acquisition target once the transport layer links.

For depth, start in 3D sensors and build the vendor's depth sample with the same include discipline. The MV-DPS200P-02 is the depth camera to build against when the cell needs point clouds instead of frames.

When a build resists, send the model, platform, SDK release and first fatal error through technical support. For a new cell, start at the camera configurator once the software path is settled.

Fixes that hide the problem

Header locations differ between Linux distributions, so trust the output of find /usr -name OpenCVConfig.cmake on your machine over any printed path, this guide's included.

Checklist before the next rebuild

• First fatal error recorded with its target and compile command.
• OpenCV generation matches the SDK's release notes.
• Development package installed for that generation.
• OpenCV_DIR points at the OpenCVConfig.cmake directory; the include root resolves the arithmetic above.
• Only the targets you need are in scope.
• A clean directory reproduces the build; the sample enumerates and the first frame arrives on time.

Related reading: missing ATL headers when building a camera SDK covers the Windows-side equivalent; camera SDK linking and CMake dependency checks takes over when headers are found but libraries are not; camera SDK build errors after a library upgrade handles version drift; and 3D camera header version mismatch addresses the other meaning of "header" — device data metadata, not a source include.