Struct SubImageFinderState

pub struct SubImageFinderState { /* private fields */ }

The main context struct. This stores the necessary buffers for the search, eters.

u8 buffers are used if conversion to grayscale is necessary, and f32 buffers for the backends that require them.

There is also a Vec<(usize, usize, f32)> used to store results.

Implementations

impl SubImageFinderState

pub fn new() -> Self

Create a SubImageFinderState

This uses the Backend::Scalar backend by default, unless the “simdeez-default-new” e is enabled (It is currently enabled by default).

See the backend and with_backend methods to change the backend.

pub fn new_opencv(threshold: Option<f32>) -> Self

Like Self::new but uses Backend::OpenCV

pub fn backend(&mut self) -> &Backend

pub fn backend_mut(&mut self) -> &mut Backend

pub fn set_backend(&mut self, new_backend: Backend)

Set the currently configured backend.

See also Self::with_backend

pub fn set_pruning(&mut self, prune_width_scale: f32, prune_height_scale: f32)

Set the currently configured prune width/height scaling.

For more information see Self::with_pruning

pub fn with_backend(self, new_backend: Backend) -> Self

Return a new state with the given backend

use find_subimage::{Backend, SubImageFinderState};
let state = SubImageFinderState::new().with_backend(Backend::Scalar {
    threshold: 0.5,
    step_x: 2,
    step_y: 1,
});

pub fn with_pruning( self, prune_width_scale: f32, prune_height_scale: f32, ) -> Self

Return a new state with the given pruning width/height scaling parameters.

These default to 0.5

pub fn find_subimage_positions<'a, 'b, T: Into<Image<'a>>, U: Into<Image<'b>>>( &mut self, search_image: T, subimage: U, channel_count: u8, ) -> &[(usize, usize, f32)]

Finds positions where the subimage is found within the search image. These positions represent the top-right corner of the subimage.

You can tweak the likelyhood of positions found with the backend’s threshold. Note that the threshold is backend-dependant.

The channel_count argument should be the number of channels for both input images (For example, 3 for an RGB image or 1 for grayscale).

The input image can optionally be converted to grayscale before applying the algorithm, see Self::find_subimage_positions_as_grayscale.

The third field of the tuples in the returned slice is the matching/distance value. Values closer to 1 mean a fuzzier match, and closer to 0 a more exact match. These values are returned sorted by distance, with the best matches first.

pub fn find_subimage_positions_with_backend<'a, 'b, T: Into<Image<'a>>, U: Into<Image<'b>>>( &mut self, search_image: T, subimage: U, backend: &Backend, channel_count: u8, ) -> &[(usize, usize, f32)]

Like Self::find_subimage_positions_as_grayscale but lets you use a different backend than the currently configured one.

pub fn find_subimage_positions_as_grayscale<'a, 'b, T: Into<Image<'a>>, U: Into<Image<'b>>>( &mut self, search_image: T, subimage: U, channel_count_search: u8, channel_count_subimage: Option<NonZeroU8>, ) -> &[(usize, usize, f32)]

Like Self::find_subimage_positions, but before finding positions it converts the images to grayscale. This can speed up runtime, but depending on the images it can be harmful to results.

This is done using internal buffers. If you reuse a SubImageFinderState for multiple images of the same size, it should only need to allocate once.

If channel_count_subimage is None, channel_count_search is used in its place.

pub fn find_subimage_positions_as_grayscale_with_backend<'a, 'b, T: Into<Image<'a>>, U: Into<Image<'b>>>( &mut self, search_image: T, subimage: U, backend: &Backend, channel_count_search: u8, channel_count_subimage: Option<NonZeroU8>, ) -> &[(usize, usize, f32)]

Like Self::find_subimage_positions_as_grayscale but lets you use a different backend than the currently configured one.

pub fn most_recent_results(&self) -> &[(usize, usize, f32)]

This returns the same as the last value returned from Self::find_subimage_positions, as long as you haven’t modified them by calling Self::most_recent_results_mut

pub fn most_recent_results_mut(&mut self) -> &mut [(usize, usize, f32)]

Gives a mutable reference to the most recent results. Calling this after Self::find_subimage_positions gives you the same slice, but with mutable access. This can be useful if you want to sort the results without allocating a new Vec.

For example, if you need to sort by y and then by x position:

use find_subimage::{Image, SubImageFinderState};
let (w, h) = (128, 128);
let mut rgb_image = vec![0u8; w * h * 3];
let (sub_w, sub_h) = (16, 16);
let mut rgb_subimage = vec![0u8; sub_w * sub_h * 3];

let mut finder = SubImageFinderState::new();
finder.find_subimage_positions((&rgb_image, w, h), (&rgb_subimage, sub_w, sub_h), 3);

let results = finder.most_recent_results_mut();
results.sort_unstable_by(|a, b| a.1.cmp(&b.1).then(a.0.cmp(&b.0)));

Trait Implementations

impl Default for SubImageFinderState

fn default() -> Self

Returns the “default value” for a type.