System designHow-to

Descriptor matcher replacement in OpenCV 4 Java: detectAndCompute

The OpenCV 4 Java descriptor matcher replacement, step by step: detectAndCompute on the detector, BRUTEFORCE_HAMMING matching, ratio filtering, and tests.

LumaSpec Vision9 min read Share on LinkedIn

On this page 10 sections
  1. 01What OpenCV 4 removed, and what stays
  2. 02What you need before the first edit
  3. 03The fix, step by step
  4. 04Prove the pipeline works
  5. 05Size the pipeline with real numbers
  6. 06Where the matcher runs
  7. 07When BRUTEFORCE_HAMMING is the wrong choice
  8. 08Common mistakes that still compile
  9. 09Pre-flight checklist
  10. 10Questions

Feature-matching samples written for OpenCV 2.4 break the moment they meet OpenCV 4: DescriptorExtractor cannot be resolved, and the Java documentation lists classes without a line of example code. The fix is short. Descriptor computation moved into the Feature2D base class in OpenCV 3, so the detector itself now fills the descriptor Mat through detectAndCompute; DescriptorMatcher still exists in org.opencv.features2d, and the matcher line in the old sample was already valid. This guide walks the migration call by call: one method replaces detect plus compute, one constant builds the right matcher for ORB's binary descriptors, and two filters separate real matches from noise. You finish with a pipeline that compiles, runs, and proves itself with a self-match test.

What OpenCV 4 removed, and what stays

Only one of the two classes in the failing sample is gone. DescriptorExtractor — the class the old code used to turn keypoints into 32-byte descriptors — was removed in the OpenCV 3.0 features2d rework and never came back. The Java bindings mirror the C++ headers, so every 2.4-era tutorial that imports it fails on 3.x and 4.x alike.

DescriptorMatcher was not removed. It still lives in org.opencv.features2d, and the line DescriptorMatcher.create(DescriptorMatcher.BRUTEFORCE_HAMMING) compiles unchanged on OpenCV 4.7. When an IDE flags both symbols, the dead DescriptorExtractor import is dragging the rest of the file down with it.

OpenCV 2.4 sample OpenCV 4 replacement
DescriptorExtractor.create(DescriptorExtractor.ORB) ORB.create() — the detector computes descriptors itself
detector.detect(img, kps) then descriptor.compute(img, kps, desc) detector.detectAndCompute(img, new Mat(), kps, desc)
DescriptorMatcher.create(DescriptorMatcher.BRUTEFORCE_HAMMING) unchanged: same class, same constant

What you need before the first edit

Area scan camerasHikrobot MV-CS200-10UM 20 MP Area Scan Camera, USB3.0, IMX183, 2nd Gen., MonoMV-CS200-10UM
Sensor format
1"
Lens mount
C-mount
Interface
USB3
Resolution
16-25 MP
$759.00View partBuild a system with it

The fix, step by step

  1. Detect and describe in one call. Create the detector, allocate one MatOfKeyPoint and one Mat per image, and let the detector fill both. The second argument is the mask; an empty new Mat() means no mask.
import org.opencv.core.Mat;
import org.opencv.features2d.MatOfKeyPoint;
import org.opencv.features2d.ORB;

Mat gray1 = new Mat();                    // scene frame, 8-bit grayscale
MatOfKeyPoint keypoints1 = new MatOfKeyPoint();
Mat descriptors1 = new Mat();             // one row per keypoint, 32 bytes each

ORB orb = ORB.create();                   // default: 500 features, 8 pyramid levels
orb.detectAndCompute(gray1, new Mat(), keypoints1, descriptors1);

The ORB class reference lists the tuning parameters as constructor arguments: ORB.create(2000) raises the feature budget, and scaleFactor widens the pyramid for parts that move in depth. Separate detect() and compute() calls still exist on the detector if you need keypoints alone; there is no extractor object any more.

  1. Create the matcher with the constant that fits ORB's descriptors. ORB emits bit strings, so distance is counted in differing bits.
import org.opencv.features2d.DescriptorMatcher;

DescriptorMatcher matcher =
        DescriptorMatcher.create(DescriptorMatcher.BRUTEFORCE_HAMMING);

BRUTEFORCE_HAMMING compares every query descriptor with every scene descriptor using XOR plus a population count. BRUTEFORCE_HAMMINGLUT computes the same distance through a lookup table — pick either; the survivor sets come out equal.

  1. Match, then filter. Raw match() returns the nearest neighbour for every query descriptor: 500 keypoints in, 500 matches out, most of them wrong on a real scene. Filtering is your job, and two filters cover nearly every case. The absolute cut keeps matches under 64 differing bits — 64 of 256 bits is a 25% mismatch, and below that a pair is nearly always the same physical feature. The ratio test from knnMatch with k = 2 keeps a match only when its nearest neighbour is clearly better than the second nearest.
import org.opencv.features2d.DMatch;
import org.opencv.features2d.MatOfDMatch;

MatOfDMatch raw = new MatOfDMatch();
matcher.match(descriptors1, descriptors2, raw);

java.util.List<DMatch> good = new java.util.ArrayList<>();
for (DMatch dm : raw.toList()) {
    if (dm.distance < 64) { good.add(dm); }
}
java.util.List<MatOfDMatch> pairs = new java.util.ArrayList<>();
matcher.knnMatch(descriptors1, descriptors2, pairs, 2);

java.util.List<DMatch> ratio = new java.util.ArrayList<>();
for (MatOfDMatch pair : pairs) {
    DMatch[] nn = pair.toArray();
    if (nn[0].distance < 0.75 * nn[1].distance) { ratio.add(nn[0]); }
}

Use the threshold on a fixtured camera with stable lighting; use the ratio test when the scene carries clutter or repeated texture, because it also discards matches that are ambiguous.

  1. Draw or consume the survivors. For a visual check, draw the filtered set; for measurement, map queryIdx and trainIdx through keypoints.toArray() to pixel coordinates.
import org.opencv.features2d.Features2d;

Mat drawn = new Mat();
Features2d.drawMatches(gray1, keypoints1, gray2, keypoints2,
        new MatOfDMatch(good.toArray(new DMatch[0])), drawn);

Prove the pipeline works

Before trusting any match count, run the self-test: match a frame against a copy of itself. Every descriptor's nearest neighbour is itself, so the largest distance in the result must be 0.0.

MatOfDMatch self = new MatOfDMatch();
matcher.match(descriptors1, descriptors1.clone(), self);

double maxDistance = 0;
for (DMatch dm : self.toList()) {
    maxDistance = Math.max(maxDistance, dm.distance);
}
System.out.println("keypoints=" + keypoints1.toArray().length
        + " descriptors=" + descriptors1.rows() + "x" + descriptors1.cols()
        + " maxSelfDistance=" + maxDistance);

Expected on the default detector: keypoints=500 descriptors=500x32 maxSelfDistance=0.0. The 32 is the ORB descriptor width in bytes; if cols prints anything else, the wrong detector is feeding the matcher. Then run two views of the same part — a few hundred matches survive the 64-bit cut — and two unrelated images, where single digits survive. Those two counts are your regression baseline, so print them at start-up.

Size the pipeline with real numbers

frameBytes = width × height × channels descriptorBytes = keypoints × 32 comparisons = queryKeypoints × trainKeypoints

The LS-CMR-0166 streams 4000 × 3000 frames at 30 fps over USB3, which makes the arithmetic concrete. One incoming colour frame is 4000 × 3000 × 3 = 36,000,000 bytes, about 34.3 MiB. Two frames held at once — template and scene — come to 72,000,000 bytes, roughly 68.7 MiB, and the two grayscale copies add 2 × 12,000,000 = 24,000,000 bytes, roughly 22.9 MiB. Descriptors are the smallest part of the budget: 2 × 2000 × 32 = 128,000 bytes, about 125 KiB. The whole working set stays under 100 MiB, so start the JVM with -Xmx512m.

Matching cost lives in the third line of the formula. 2000 × 2000 = 4,000,000 Hamming distances, each an XOR over eight 32-bit words plus a population count, and native OpenCV clears that in tens of milliseconds on one core. At 30 fps the frame budget is 1000 / 30 = 33.3 ms, so 2000 keypoints a side fits the budget, and the default 500-feature detector leaves four times the matching headroom. Detection cost, unlike matching, scales with pixels; on 12 MP frames that is the term to keep off the robot-control thread.

Area scan cameras12 MP USB3 area scan camera, IMX226, 1/1.7" rolling shutter, 30 fps, 4000 × 3000 resolution (LS-CMR-0166)LS-CMR-0166
Sensor format
1/1.7"
Interface
USB3
Resolution
12 MP
Shutter
Rolling
$560.00View partBuild a system with it

Where the matcher runs

The matcher is CPU work in the middle of a camera-to-decision chain, so the machine matters as much as the code. On the vision controllers side, a controller with 8 GB of memory such as the MV-VC3301H-128G66 runs the JVM, the native library and the inspection logic in one box, with light channels left over. On the smart cameras side, an x86-platform model such as the LS-SMC-0017, 8.8 MP with a global shutter, hosts the matching next to the sensor and ships a verdict over the network instead of pixels. When plain feature matching stops separating your parts, AI versus rule-based smart camera inspection draws that line. And if the matcher runs inside an HMI project rather than a standalone program, adding OpenCV Java bindings to an Ignition Vision project covers the classpath and native-library wiring.

Vision controllersHikrobot MV-VC3301H-128G66 I3-8100, 8GB+128G SSD, No PoE, PCIe expansion supported, Incl. VM6200Pro licenseMV-VC3301H-128G66
LAN ports
5+ LAN ports
USB 3 ports
3-4 USB 3 ports
Light outputs
4 built-in channels
Memory
8 GB
$2,419.00View partBuild a system with it
Smart cameras & vision sensorsSC / SC smart camera (X86 platform), 8.8 MP, USB3, Color/Mono, global shutter (LS-SMC-0017)LS-SMC-0017
Interface
USB 2.0
Resolution
6-10 MP
Sensor format
1"
Shutter
Global
$1,359.00View part

When BRUTEFORCE_HAMMING is the wrong choice

  • Descriptor count past roughly 10,000 a side. Brute-force cost grows as the product of the two counts: 50,000 × 50,000 = 2.5 billion comparisons, seconds even in native code. Switch to approximate search with LSH:
import org.opencv.features2d.FlannBasedMatcher;
import org.opencv.flann.LshIndexParams;

FlannBasedMatcher lsh = new FlannBasedMatcher(new LshIndexParams(20, 15, 2));

The FlannBasedMatcher reference covers the index parameters. LSH trades a share of true matches for sub-linear lookup, so measure the survivors you lose on your two-view baseline before committing to it.

  • Large viewpoint or scale swings. ORB covers modest rotation and scale changes. When a robot-mounted camera sees the part from changing distances and angles, SIFT.create() (in OpenCV since 4.4) survives swings ORB does not, at several times the compute cost. Its descriptors are 128-element floats: build the matcher with DescriptorMatcher.create(DescriptorMatcher.BRUTEFORCE) and run the ratio test at 0.7 to 0.8, not with a Hamming matcher.
  • Mixed detectors. match() requires both descriptor Mats to share a type; ORB produces CV_8U, SIFT CV_32F, and crossing them throws a CvException at run time, long after the compiler was happy. One detector type per matcher.

The standing decisions: fixtured camera and stable distance — ORB plus BRUTEFORCE_HAMMING. Robot or handheld viewpoint — SIFT plus BRUTEFORCE. Tens of thousands of descriptors — ORB plus LSH.

Common mistakes that still compile

  • Searching for a replacement import. There is none. org.opencv.features2d no longer exports a descriptor-extractor class of any name; the detector is the extractor. Java builds fail this way wherever a library ships several similarly named classes — importing the right Rect class in an OpenCV Android build is the same repair pattern.
  • Feeding colour Mats. Imgcodecs.imread returns BGR and Android bitmaps converted with Utils.bitmapToMat return RGBA; ORB requires single-channel 8-bit input and throws on anything else. Convert first — Imgproc.COLOR_BGR2GRAY for imread, Imgproc.COLOR_RGBA2GRAY for bitmaps.
  • Sharing one MatOfKeyPoint between images. The second detectAndCompute overwrites the first; allocate one per image.
  • Drawing raw matches. drawMatches with the unfiltered list paints noise and hides the fact that the filter was skipped.

Pre-flight checklist

  • Jar and native library from the same OpenCV 4 build.
  • Both images 8-bit grayscale before detectAndCompute.
  • descriptors.cols() prints 32 for ORB.
  • Matcher constant matches the detector: binary for BRUTEFORCE_HAMMING, float for BRUTEFORCE.
  • Self-match prints maxSelfDistance=0.0.
  • Filter before counting: threshold 64, or ratio 0.75 through knnMatch.
  • -Xmx512m for 12 MP image pairs, and 2000 keypoints a side to hold a 33.3 ms frame budget.

From here the fastest route to a running station is the system configurator started at the camera step; bring part size, standoff distance and cycle time to the contact page and the applications team will size the rest of the chain.

Questions

Which OpenCV version removed DescriptorExtractor?

OpenCV 3.0, in the 2015 features2d rework: descriptor computation moved into the Feature2D base class and the standalone extractor class was deleted from the C++ headers and from every language binding. That is why 2.4-era tutorials break identically on 3.x and 4.x. detectAndCompute has been the supported path since 3.0 and is unchanged in 4.7.

Can FlannBasedMatcher match ORB descriptors in Java?

Yes, but only through an LSH index: new FlannBasedMatcher(new LshIndexParams(20, 15, 2)). The default KD-tree index accepts 32-bit float descriptors and rejects ORB's CV_8U rows at match time. LSH pays off above roughly 10,000 descriptors a side; below that BRUTEFORCE_HAMMING is faster and returns exact nearest neighbours.

How do I switch this code to SIFT?

Replace ORB.create() with SIFT.create(), available in OpenCV 4.4 and later, and keep the same detectAndCompute call. SIFT emits float descriptors instead of bit strings, so a Hamming matcher no longer applies — use the plain brute-force float matcher and run the ratio test at 0.7 to 0.8. Expect several times ORB's compute cost in exchange for surviving larger viewpoint and scale changes.

What Hamming distance counts as a good ORB match?

Start at 64 of 256 bits, a 25% mismatch: below that a pair is almost always the same physical feature. Tighten to 48 on fixtured parts under stable lighting, and loosen toward 80 in cluttered scenes. Track the mean distance of survivors between runs; a steady rise means the template no longer matches the part as built, not that the code drifted.

How many keypoints should ORB.create() keep?

The default is 500, and it answers the question of whether the template is present. ORB.create(2000) locates a part to a few pixels and still fits a 33.3 ms budget at 30 fps. Past about 5,000 features the match count grows as the product of both sides while localization gains stall on machined and molded parts.