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
- The OpenCV 4.x Java jar and its native library must come from the same build, or the first call fails with
UnsatisfiedLinkError; matching the OpenCV jar to its native library covers that repair. - Two 8-bit grayscale
Mats. Templates load from files withImgcodecs.imread, which returns BGR — convert withImgproc.COLOR_BGR2GRAY. A scene frame from a camera SDK arrives as a buffer you can wrap in an OpenCV cv::Mat without copying, and if the template exists only as a bitmap in your interface, copying a GUI bitmap into a Mat without a file skips the round trip. - A camera that delivers the frames. On the area scan cameras side, a 20 MP USB3.0 model such as the MV-CS200-10UM is a comfortable source, and the 16, 20 or 24 MP camera comparison walks the trade-offs; the camera finder filters by mount and interface.
- Sensor format
- 1"
- Lens mount
- C-mount
- Interface
- USB3
- Resolution
- 16-25 MP
The fix, step by step
- Detect and describe in one call. Create the detector, allocate one
MatOfKeyPointand oneMatper image, and let the detector fill both. The second argument is the mask; an emptynew 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.
- 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.
- 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 fromknnMatchwith 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.
- Draw or consume the survivors. For a visual check, draw the filtered set; for measurement, map
queryIdxandtrainIdxthroughkeypoints.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
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.
- Sensor format
- 1/1.7"
- Interface
- USB3
- Resolution
- 12 MP
- Shutter
- Rolling
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.
- LAN ports
- 5+ LAN ports
- USB 3 ports
- 3-4 USB 3 ports
- Light outputs
- 4 built-in channels
- Memory
- 8 GB
- Interface
- USB 2.0
- Resolution
- 6-10 MP
- Sensor format
- 1"
- Shutter
- Global
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 withDescriptorMatcher.create(DescriptorMatcher.BRUTEFORCE)and run the ratio test at 0.7 to 0.8, not with a Hamming matcher. -
Mixed detectors.
match()requires both descriptorMats to share a type; ORB producesCV_8U, SIFTCV_32F, and crossing them throws aCvExceptionat 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.features2dno 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.imreadreturns BGR and Android bitmaps converted withUtils.bitmapToMatreturn RGBA; ORB requires single-channel 8-bit input and throws on anything else. Convert first —Imgproc.COLOR_BGR2GRAYfor imread,Imgproc.COLOR_RGBA2GRAYfor bitmaps. -
Sharing one
MatOfKeyPointbetween images. The seconddetectAndComputeoverwrites the first; allocate one per image. -
Drawing raw matches.
drawMatcheswith 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 forBRUTEFORCE. - Self-match prints
maxSelfDistance=0.0. - Filter before counting: threshold 64, or ratio 0.75 through
knnMatch. -
-Xmx512mfor 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.



