OpenCV setNumThreads: cap CPU usage while streaming

A camera stream that pushes all 32 cores to 40% while motion control and PLC comms starve is not a camera fault. It is OpenCV's default thread pool using every logical core it can find. Any per-frame operation with a parallel implementation wakes the whole pool. The fix is one call, cv::setNumThreads(N), plus a sizing rule that protects the frame rate while you bound the load. This page gives you the mechanics of where the threads come from, the cap call with a readback that proves it took, a decision table for N, the arithmetic that predicts what a cap does to frame rate, and the measurements that confirm the result on a running line.

Why does a camera stream load every CPU core at once?

OpenCV sizes its internal worker pool to every logical core on the machine unless you tell it otherwise. On a 32-thread host, a single 60 fps stream from an area scan camera can hold all 32 cores near 40% each.

The pool belongs to OpenCV's parallel framework, the machinery behind parallel_for_. Every function with a parallel implementation uses it: color conversion, resize, thresholding, and the internal conversion some camera wrappers run before handing you a frame. The pool is built once from the hardware's logical core count and keeps that size until you set it.

The measured case behind the numbers in this guide: one small preview stream at 60 fps held 32 threads at roughly 40% each. Multiply it out: 32 × 40% = 1,280% of one core's capacity, about 12.8 cores of demand for a picture a few hundred pixels tall. Most of it is not pixel math. Idle pool workers spin for a short while for the next job instead of sleeping immediately, so per-frame overhead wakes all of them, which is why the load spreads instead of concentrating. Dropping the same stream to 30 fps cut it to about 15% per thread: 32 × 15% = 480%, roughly 4.8 cores.

What are all those extra threads and apparent processes?

The swarm you see in htop is usually one program's thread pool, not many processes. Linux tools list each thread of a process as its own row by default, and the pool wakes because the frame loop reaches OpenCV functions that parallelize internally.

htop shows threads as rows, so a streaming program with a 32-slot pool looks like 32 entries; task managers that hide threads give the opposite impression. Either way the count is a pool you size, not a runaway program you kill.

What wakes it: every per-frame call with a parallel implementation. The usual suspects in a streaming loop are color conversion, resizing to a preview, and any conversion a camera wrapper performs inside its own get-frame function before it returns an image. Each job is small; the pool's size, not the work's size, decides how many cores light up. That is why the same test collapsed onto a single core as soon as the preview shrank.

How to cap OpenCV's threads with cv::setNumThreads

Call cv::setNumThreads(N) once at process start with N as the worker count you will allow. The setting applies to OpenCV's pool for the whole process, and N = 0 is a documented special case that disables threading optimizations so every function runs sequentially.

Zero is the diagnostic setting, not a production one; production caps are small positive numbers. In C++:

#include <opencv2/core.hpp>

cv::setNumThreads(2);            // documented API: cap the pool at 2 workers

int pool = cv::getNumThreads(); // documented API: readback, pool == 2 proves it took

In Python the same calls are cv2.setNumThreads() and cv2.getNumThreads():

import cv2

cv2.setNumThreads(2)        # cap before the first OpenCV call
pool = cv2.getNumThreads()  # returns 2 when the cap took effect

Read the pool back right after startup: getNumThreads() returns the current worker count and should equal the value you set.

What thread count to set on a shared host

Start at 2 worker threads per camera process on any host that shares CPU with time-critical code, keep the sum of caps at or below the physical core count, and leave the default pool in place only where the vision application owns the whole machine.

Two threads per process bounds the worst case at roughly 200% CPU plus a main-thread share of about 50%. On an 8-core machine with 800% capacity that leaves about 800% − 250% = 550%, some 5.5 cores, for acquisition, the OS and everything else you run.

Multi-camera hosts stay clean when each camera owns a process with its own cap; one camera per process is the pattern to follow when several programs share a machine.

When the host itself is the root cause — an office desktop doing line duty — a purpose-built controller removes the conflict at the source. The same family's three tiers make the sizing ladder visible:

All 3 share: Certification CE, KC. Values as printed in each product's data sheet; open a part for its drawing and full specifications.

Choose by stream count and cabling: the entry tier carries one or two GigE streams, the mid tier suits a multi-camera cell around an Intel Core i3, and the top tier adds PoE camera ports and an Intel Core i5 for heavier pipelines. The mid tier covers the common single-camera shared cell — Intel Core i3 processor, 8 GB of memory, 5+ LAN ports, 4 built-in light channels and PCIe expansion in the MV-VC3301H-128G66:

Size the cap on a controller exactly as on any host: count physical cores, subtract acquisition and OS needs, and keep every process's cap inside the remainder.

Why did the frame rate drop after capping the threads?

A cap smaller than the stream's real demand turns a CPU problem into a frame-rate problem. Against 12.8 cores of demand, a 2-thread pool delivers about 60 × 2 / 12.8 ≈ 9 fps from a 60 fps camera.

The decision rule: cut demand first — fewer pixels per frame, fewer conversions, lower preview rate — until a small cap meets it with a thread to spare. Otherwise raise N until delivered fps holds with 20-30% headroom on the capped cores. Lowering demand is the only option that also frees cores for your other processes. When processing still cannot keep pace with acquisition, that is the acquisition-versus-processing frame rate gap, and late frames surface as wait timeouts before anything else notices.

How to verify the cap on a live stream

Three numbers prove the fix: a getNumThreads() readback equal to the value you set, total process CPU at or below cap × 100% plus a few percent of main thread, and a delivered frame rate equal to the camera setting held over a ten-minute run at worst-case resolution.

1. Read the pool back with cv2.getNumThreads() immediately after startup — expect 2, or your N. If it returns the logical core count, the cap never ran in this process.
2. Watch the process total in htop for five minutes at worst-case resolution and frame rate: two busy threads plus a small main-thread share, not a wall of 40% rows.
3. Count delivered frames over ten minutes and divide by time; compare with the configured camera fps. Read the rate from the API rather than guessing from a display timer — read the frame rate reliably in OpenCV covers the method.
4. Run the other time-critical process beside the stream and confirm its loop timing is back to normal.
5. Repeat the whole set after any software update; pool behavior differs between OpenCV versions and builds.

When is the default thread pool the right choice?

Leave the pool at its default on a machine that runs nothing but the vision application. One worker per logical core is the fastest configuration there, and capping it costs frame rate while protecting nobody.

The cap exists to protect co-residents: an HMI, database writes, PLC communications, motion loops on the same box. If any of those share the machine, it is a shared host — cap it. If nothing shares it, the default pool gives the shortest processing time per frame, and the right move is sizing the machine rather than tuning the pool. The vision controllers category exists for exactly that step.

How to keep the CPU load low for the long run

Prevention is arithmetic and hygiene: keep per-frame pixels and conversions to what the inspection actually needs, run one process per camera with its own cap, and pull the interface-level levers before you give any pool more threads.

• Convert once: request the pixel format your algorithm needs at capture instead of converting, resizing and converting again down the chain.
• Right-size the region of interest: demand scales with pixels × frame rate, so a smaller ROI is the cheapest CPU on offer.
• Convert at the rate you consume: if the consumer runs at 30 fps, do not convert 60.
• Bound the frame queue so a slow consumer drops frames instead of growing memory: bound the queue and reuse frames.
• Trade latency, not cores: GigE interrupt moderation cuts per-packet CPU at a small latency cost.
• Replace spin loops with blocking waits: replace busy-wait acquisition removes a full core of constant burn by itself.
• Pin the OpenCV version on validated machines and re-measure CPU and fps after upgrades.

More host-side tuning guides sit on the systems topic page. If the audit ends with a host that was undersized from the start, bring your stream settings and measured demand to the contact page and we will size it with you.