3D visionTroubleshooting

Fix the ndarray is not C-contiguous error: numpy 2.0 ABI break

The ndarray is not C-contiguous error is a numpy 2.x ABI break in depth-camera wrappers built with pybind11 older than 2.12. Pin numpy 1.26.4 or rebuild.

LumaSpec Vision9 min read Share on LinkedIn

On this page 9 sections
  1. 01What the error actually says
  2. 02Why it appeared after the upgrade
  3. 03The two fixes: pin numpy or rebuild the wrapper
  4. 04Worked example: prove the break, then prove the fix
  5. 05All zeros after a late copy is a second bug
  6. 06The test that proves the wrapper is fixed
  7. 07Prevention: keep the version pair pinned
  8. 08When the wrapper is unmaintained
  9. 09Questions

Your depth camera's Python examples ran fine yesterday and throw ValueError: ndarray is not C-contiguous today, while the vendor viewer and the C++ samples still stream normally. The camera, its firmware and the USB link are healthy. The break is in the Python wrapper. It was built against pybind11 older than 2.12, which cannot read numpy 2.x arrays, so a routine pip upgrade to numpy 2.2 breaks every example between one session and the next. Here you will confirm the mismatch with one command, fix it by pinning numpy 1.26.4 or by rebuilding the wrapper with pybind11 2.12 or newer, and tell this bug apart from the one it mimics: all-zero frames after a late .copy(order='C').

What the error actually says

ndarray is not C-contiguous is numpy's conversion layer refusing to hand out a flat view of memory that is not a flat block. "C-contiguous" is the buffer protocol's term, as Python's PEP 3118 defines it, for memory stored as one row-major chunk: element (row, column) sits at row × row_bytes + column × itemsize, with no gaps between rows.

A depth-camera SDK's Python wrapper turns every frame into a numpy array. Wrappers compiled against numpy 1.x headers with pybind11 below 2.12 misread numpy 2.x type and stride metadata, so the conversion fails the contiguity check even for a perfectly contiguous frame. pybind11's documentation sets 2.12 as the minimum for NumPy 2.0 support, and plenty of SDK requirement files still pin pybind11 2.11.0.

That is also why the viewer and the C++ examples keep working: they never touch numpy and consume the SDK's native image types, so the mismatch cannot reach them. If those run, the sensor, emitter and cable are fine — spend no time on them.

Why it appeared after the upgrade

The wrapper binary on disk did not change; the numpy underneath it did. The usual triggers:

  • You upgraded an unrelated package and pip resolved numpy 2.2 as a dependency.
  • You built a fresh virtual environment and nothing pinned numpy, so pip defaulted to 2.x.
  • The SDK's requirements file pins pybind11 2.11.0 but leaves numpy unpinned, so the old wheel survives until numpy 2.x arrives.

The failure is deterministic: the same error on every frame, after reboot, in every example script. If only some frames come back wrong, that is a different failure — jump to the zeros section below.

The two fixes: pin numpy or rebuild the wrapper

Pick one and make the version pair coherent again.

Fix 1 — pin numpy below 2.0 (five minutes, no compiler).

python -m pip install "numpy==1.26.4"

numpy 1.26.4 is the final release of the 1.x line, and wrappers of that era were built and tested against it. Write the pin into the SDK's requirements file as numpy<2.0 so the next bulk upgrade cannot undo it.

Fix 2 — rebuild the wrapper for numpy 2.x (keeps you current, needs a compiler).

Edit the SDK's requirements file and delete the pybind11 pin (the problematic ones read pybind11==2.11.0), then upgrade pybind11 and reinstall the wrapper from its source folder:

python -m pip install --upgrade "pybind11>=2.12"
python -m pip install --force-reinstall .

If the SDK ships a newer wrapper release whose notes state numpy 2 support, installing that release does the same job without a build.

Decision: cannot build (managed machine, air-gapped line, wheels only)? Pin numpy 1.26.4 today; it is a stable, maintenance-only version and unblocks the line at once. Control the build environment, or the vendor has a rebuilt release? Rebuild or upgrade with pybind11 2.12 or newer and stay on numpy 2.x, where current fixes land. After either fix, python -m pip show numpy pybind11 must show a coherent pair — not a pybind11 2.11.0 pin sitting under numpy 2.2.

Worked example: prove the break, then prove the fix

The version matrix is the whole diagnosis:

numpy at runtime wrapper built with result on every frame
2.2 pybind11 2.11.0 ValueError: ndarray is not C-contiguous
1.26.4 pybind11 2.11.0 frames convert normally
2.2 pybind11 2.12 or newer frames convert normally

Running the middle row costs one downgrade and one example script. If numpy 1.26.4 makes the error vanish, the wrapper is the problem and the pin or rebuild is the cure.

Now the numbers behind "contiguous" for a typical depth frame of 1024 × 1024 pixels at 16 bits:

  • 16-bit depth: 2 bytes per pixel.
  • One row: 1024 px × 2 B/px = 2,048 B.
  • Whole frame: 2,048 B × 1,024 rows = 2,097,152 B = 2 MiB.
  • At 15 fps, the next frame lands every 1000 ms ÷ 15 = 66.7 ms.

A C-contiguous buffer has a row stride of exactly 2,048 B. If the SDK pads rows to an alignment boundary, the stride is larger, the buffer genuinely is not contiguous, and a copy with order='C' before conversion restores it — the stride mechanics are covered in Numpy depth image to point cloud: fix strides and dtypes.

frame period (ms) = 1000 / frame rate (fps) = 1000 / 15 = 66.7 ms

All zeros after a late copy is a second bug

Forcing the conversion — frame.get_data().copy(order='C'), with get_data() being the accessor the vendor's own examples call — and reading all zeros is a different failure that mimics the first: you touched the frame after the wrapper had already released it.

SDKs recycle a small ring of frame buffers. Once your grab loop moves on, that memory belongs to the next capture or has been wiped, so a late copy returns zeros or a blend of two frames.

The fix is ordering, not flags: copy inside the frame-valid window, before you release or return the frame. At 15 fps the window is 66.7 ms and copying 2 MiB is a sub-millisecond operation, so the copy is never the bottleneck — its position is. Point the camera at a lit wall and check np.count_nonzero(arr): a real scene gives thousands of non-zero pixels, not 0.

The same ordering rule keeps callback code honest; the buffer-copying pattern is the one behind Torn frames in a camera callback: copy the buffer before you queue it and Push the camera buffer back only after copying your frame data. For editing depth values after a safe copy, Modify depth frame data in numpy so changes are persistent covers the dtype and read-only traps.

The test that proves the wrapper is fixed

import numpy as np

frame = grab_one_depth_frame()  # illustrative name: your SDK's grab call for one frame
raw = frame.get_data()          # get_data(): the accessor the vendor's Python examples call
arr = np.frombuffer(raw, dtype=np.uint16).reshape(1024, 1024)  # 1024 x 1024, uint16 depth

assert arr.flags["C_CONTIGUOUS"], "wrapper still broken: recheck numpy and pybind11"
assert np.count_nonzero(arr) > 0, "all zeros: late copy, see the section above"
print(arr.min(), arr.max())

np.frombuffer over a read-only buffer gives a read-only array; copy it first if you need to write, as the persistent-editing article above shows. Run the test pointing at a wall about three metres away. Most depth sensors report millimetres, so a healthy frame prints a minimum near 0 (dropouts read 0) and a maximum around 3,000. No error plus counts in that range proves the pair — numpy 2.x with pybind11 2.12 or newer, or numpy 1.26.4 with the old wheel — on your machine.

Prevention: keep the version pair pinned

  • Prebuilt wrapper: pin numpy<2.0 in the requirements file and hold the pin until the vendor ships a wheel built with pybind11 2.12 or newer.
  • Source build: require pybind11>=2.12, leave numpy at 2.x, and rebuild after each major numpy release.
  • After any bulk pip install -U, run python -m pip show numpy pybind11 before the first grab; one transitive jump to numpy 2.2 is what started this.
  • Maintaining internal tools on several machines? Build the wrapper in CI twice, once against numpy 1.26.4 and once against numpy 2.x, so an ABI break shows up as a red build instead of a stopped station.

When the wrapper is unmaintained

Some depth-camera lines ship Python wrappers that lag numpy by years, and if no rebuild against pybind11 2.12 ever ships, you are pinned to numpy 1.26.4 for the life of the camera. That is a workable state, but weigh it at the next hardware decision: a maintained SDK with current pybind11, numpy 2 wheels and working examples is worth as much as a fraction of a millimetre of depth accuracy, because a version bump is otherwise enough to idle your station for a day.

Browse the 3D sensors category and the camera finder with the SDK's release notes open beside you, then spec the whole station in the configurator below. The 3D topic page collects the rest of the depth-camera fixes on this site.

Build the whole station

The configurator matches a camera, lens, light, light controller and cables to each other, step by step, and lists only parts that fit what you already picked.

Start with the camera

Questions

Is my depth camera damaged when Python raises ndarray is not C-contiguous?

No. The error comes from the numpy conversion inside the Python wrapper, not from the sensor, the emitter or the USB link. The vendor viewer and the C++ examples read the same frames through the SDK's native image types and keep working, which is itself the diagnostic. If they run, work on the wrapper and its numpy and pybind11 versions rather than swapping cables or reinstalling firmware.

Which numpy version should I pin for an older SDK wrapper?

Pin numpy 1.26.4, the final release of the 1.x line. Wrappers from the pybind11 2.11 era were built and tested against numpy 1.x, and 1.26.4 sits closest to 2.0 in behaviour. Write the pin as numpy<2.0 in your requirements file rather than an exact equality, then re-run pip show numpy after any bulk upgrade, because one transitive install to 2.x brings the error straight back.

Can I keep numpy 2.x without rebuilding the wrapper?

Only if the wrapper wheel itself was built with pybind11 2.12 or newer, which pybind11's documentation sets as the minimum for NumPy 2.0 support. Check the SDK's release notes for a numpy 2 statement. If the newest wheel still pins pybind11 2.11.0, no runtime setting helps: either rebuild from source against pybind11 2.12+ or stay pinned below numpy 2.0.

Why does .copy(order='C') return all zeros even after the fix?

Because the copy ran after the wrapper released the frame. SDKs reuse a small ring of frame buffers, so a copy made outside the frame-valid window reads the next capture's memory or a wiped buffer. Copy inside the grab callback before the frame is returned: at 15 fps the window is 66.7 ms, and moving 2 MiB is a sub-millisecond copy on any current machine.

What does C-contiguous mean for a depth frame in practice?

Memory stored as one flat row-major block, as the buffer protocol in PEP 3118 defines it. In a 16-bit frame each pixel sits at row × row_bytes + column × 2 bytes. A 1024-pixel row then has a 2,048-byte stride and a 1024 × 1024 frame totals 2 MiB. Rows padded to an alignment boundary break contiguity; a copy with order='C' restores it.

Do I need to reinstall the camera driver or firmware for this error?

No. The viewer and the C++ examples prove the device, firmware and USB path are sound, and a driver reinstall changes nothing in the Python conversion layer. Change only the Python side: pin numpy 1.26.4 or rebuild the wrapper with pybind11 2.12 or newer, confirm the pair with pip show numpy pybind11, then run the depth example again.