Crate find_subimage[−][src]
Expand description
This crate provides basic functionality to find likely positions of a subimage within a larger image by calculating an image distance. It has a naive scalar implementation in rust, and a simd implementation that selects the best implementation based on cpu features at runtime in rust using the simdeez crate. It also provides an implementation which uses OpenCV’s (A C++ library) matchTemplate function using the opencv-rust crate through an optional off-by-default feature. It can also optionally convert images to grayscale before applying the algorithms.
Here’s a simple example showing how to use the API:
use find_subimage::{Image, SubImageFinderState};
// Make a dummy 128x128 black image with a red dot at (50, 0)
let (w, h) = (128, 128);
let mut rgb_image = vec![0u8; w * h * 3];
rgb_image[50 * 3] = 250;
// Make a dummy 32x32 black image
// with a red dot at (0, 0)
let (sub_w, sub_h) = (32, 32);
let mut rgb_subimage = vec![0u8; sub_w * sub_h * 3];
rgb_subimage[0] = 250;
let mut finder = SubImageFinderState::new();
// These are (x, y, distance) where x and y are the position within the larger image
// and distance is the distance value, where a smaller distance means a more precise match
let positions: &[(usize, usize, f32)] =
finder.find_subimage_positions((&rgb_image, w, h), (&rgb_subimage, sub_w, sub_h), 3);
let max: Option<&(usize, usize, f32)> = positions
.iter()
.min_by(|(_, _, dist), (_, _, dist2)| dist.partial_cmp(dist2).unwrap());
println!("The subimage was found at position {:?}", &max);
assert_eq!(Some((50, 0)), max.map(|max| (max.0, max.1)));
// find_subimage_positions actually returns the results sorted by distance already,
// so we can skip finding the minimum
assert_eq!(Some((50, 0)), positions.get(0).map(|max| (max.0, max.1)));The most important functions provided are find_subimage_positions and find_subimage_positions_as_grayscale.
You may find their “_with_backend” versions useful.
By default, this library prunes results that are close together. You can disable (Set to 0) or tweak this using with_pruning.
You can look at the page for the Backend enum to learn about the possible backends.
There are some examples in the /examples folder in the repository.
Structs
A simple struct to group (bytes, width, height) arguments
The main context struct. This stores the necessary buffers for the search, eters.
Enums
The backend/algorithm to use.
Constants
The default value used in SubImageFinderState::new and SubImageFinderState::default
The default value used in SubImageFinderState::new_opencv