From b0db1603ee575b8f7f0a747263cb6e6c982449fc Mon Sep 17 00:00:00 2001 From: Michael Rook Date: Sat, 18 Dec 2021 21:05:59 +1100 Subject: [PATCH] Version bump Add doc comments --- Cargo.toml | 2 +- README.md | 58 +++++++++++++++++++++++++++++++++++++--------------- src/lib.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++++++ src/main.yml | 2 +- 4 files changed, 97 insertions(+), 19 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index f82e732..30533fa 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "imeq" description = "imeq aims to quickly compare two images to see if they are the same image" -version = "0.0.2" +version = "0.1.0" edition = "2021" categories = ["multimedia::images"] exclude = ["images/*"] diff --git a/README.md b/README.md index adfde89..2ad58c5 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ imeq-rs aims to quickly compare two images to see if they are the same image. -## Installation +## Standalone + +### Installation ``` cargo install imeq ``` -## Usage +### Usage ``` USAGE: imeq @@ -19,13 +21,7 @@ ARGS: Sets the second image to use ``` -## Building -Compiles to: `target/release/imeq` -``` -cargo build --release -``` - -## Benchmark +### Benchmark The below benchmarks have been done on a 2020 M1 Mac Mini with 16gb of ram and 256gb ssd, `hyperfine -w 3` is used and that command is then ran 3 times (outside of -w 3) and the result of the third run has been noted. `baseline.jpeg` and `baseline_by_another_name.jpeg` should be identical, apart from the name. @@ -34,34 +30,63 @@ The below benchmarks have been done on a 2020 M1 Mac Mini with 16gb of ram and 2 `modified.jpeg` has been modified so that the very last (bottom right) pixel is red. - - -### hyperfine -w 3 'target/release/imeq images/baseline.jpeg images/baseline.jpeg' +#### hyperfine -w 3 'target/release/imeq images/baseline.jpeg images/baseline.jpeg' ```bash Time (mean ± σ): 1.1 ms ± 0.3 ms [User: 0.6 ms, System: 0.3 ms] Range (min … max): 0.8 ms … 2.6 ms 857 runs ``` -### hyperfine -w 3 'target/release/imeq images/baseline.jpeg images/baseline_by_another_name.jpeg' +#### hyperfine -w 3 'target/release/imeq images/baseline.jpeg images/baseline_by_another_name.jpeg' ```bash Time (mean ± σ): 5.5 ms ± 0.4 ms [User: 7.4 ms, System: 2.3 ms] Range (min … max): 5.1 ms … 7.5 ms 308 runs ``` -### hyperfine -w 3 'target/release/imeq images/baseline.jpeg images/flipped.jpeg' +#### hyperfine -w 3 'target/release/imeq images/baseline.jpeg images/flipped.jpeg' ```bash Time (mean ± σ): 93.7 ms ± 3.4 ms [User: 443.6 ms, System: 54.2 ms] Range (min … max): 90.4 ms … 102.8 ms 31 runs ``` -### hyperfine -w 3 'target/release/imeq images/baseline.jpeg images/modified.jpeg' +#### hyperfine -w 3 'target/release/imeq images/baseline.jpeg images/modified.jpeg' ```bash Time (mean ± σ): 113.1 ms ± 0.9 ms [User: 471.1 ms, System: 53.4 ms] Range (min … max): 111.4 ms … 115.5 ms 26 runs ``` +## As a library -## Credits +### Installation +Add the following line to your Cargo.toml file: +``` +imeq = "0.1.0" +``` +or if you have `cargo edit` installed. +``` +cargo add imeq +``` + +### Usage +```rust +let image_1 = "images/baseline.jpeg".to_string(); + +let image_2 = "images/modfied.jpeg".to_string(); + +let images_match = imeq::Compare::new(image_1, image_2) + .enable_check_images_have_same_path() + .enable_check_image_hashes_match() + .enable_check_images_dimensions_match() + .enable_check_images_pixels_match() + .are_match(); + +if images_match { + println!("Images are a match"); +} else { + println!("Images are not a match"); +} +``` + +## Credits - [Handmade Web & Design](https://github.com/handmadeweb) - [Michael Rook](https://github.com/michaelr0) - [All Contributors](https://github.com/michaelr0/imeq-rs/graphs/contributors) @@ -69,5 +94,4 @@ The below benchmarks have been done on a 2020 M1 Mac Mini with 16gb of ram and 2 [Goat Image](https://unsplash.com/photos/J9wZ6D2kYPw) by [Florian van Duyn](https://unsplash.com/@flovayn) ## License - The MIT License (MIT). Please see [License File](https://github.com/michaelr0/imeq-rs/blob/main/LICENSE.md) for more information. diff --git a/src/lib.rs b/src/lib.rs index 2a0e4af..513bccd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,14 +1,60 @@ +//! imeq-rs aims to quickly compare two images to see if they are the same image. +//! Compare images +//! # Example +//! ```no_run +//! let image_1 = "images/baseline.jpeg".to_string(); +//! +//! let image_2 = "images/modfied.jpeg".to_string(); +//! +//! let images_match = imeq::Compare::new(image_1, image_2) +//! .enable_check_images_have_same_path() +//! .enable_check_image_hashes_match() +//! .enable_check_images_dimensions_match() +//! .enable_check_images_pixels_match() +//! .are_match(); +//! +//! if images_match { +//! println!("Images are a match"); +//! } else { +//! println!("Images are not a match"); +//! } +//! ``` + use image::{DynamicImage, GenericImageView, Pixels}; use rayon::prelude::*; use ring::digest::{self}; use std::{collections::HashMap, fs::File, io::Read}; +/// Compare images +/// # Example +/// ```no_run +/// let image_1 = "images/baseline.jpeg".to_string(); +/// +/// let image_2 = "images/modfied.jpeg".to_string(); +/// +/// let images_match = imeq::Compare::new(image_1, image_2) +/// .enable_check_images_have_same_path() +/// .enable_check_image_hashes_match() +/// .enable_check_images_dimensions_match() +/// .enable_check_images_pixels_match() +/// .are_match(); +/// +/// if images_match { +/// println!("Images are a match"); +/// } else { +/// println!("Images are not a match"); +/// } +/// ``` pub struct Compare<'a> { + /// Images to compare images: [String; 2], + /// Checks that have been enabled or disabled checks: HashMap<&'a str, bool>, } +/// Compare images impl Compare<'_> { + /// Create a new Image comparson pub fn new(image_1: String, image_2: String) -> Self { let mut compare = Compare { images: [image_1, image_2], @@ -23,32 +69,39 @@ impl Compare<'_> { compare } + /// Enable or disable a check pub fn enable_check(&mut self, check: &'static str) -> &mut Self { self.checks.insert(check, true); self } + /// Enable check for images having the same path pub fn enable_check_images_have_same_path(&mut self) -> &mut Self { self.enable_check("images_have_same_path") } + /// Enable check for image hashes matching pub fn enable_check_image_hashes_match(&mut self) -> &mut Self { self.enable_check("image_hashes_match") } + /// Enable check for image dimensions matching pub fn enable_check_images_dimensions_match(&mut self) -> &mut Self { self.enable_check("image_dimensions_match") } + /// Enable check for image pixels matching pub fn enable_check_images_pixels_match(&mut self) -> &mut Self { self.enable_check("image_pixels_match") } + /// Check to see if check is enabled fn is_check_enabled(&self, check: &'static str) -> bool { *self.checks.get(check).unwrap_or(&false) } + /// Compare images and return if they are a match pub fn are_match(&self) -> bool { if self.is_check_enabled("images_have_same_path") && self.images.first() == self.images.last() @@ -113,6 +166,7 @@ impl Compare<'_> { false } + /// Compare images and return if they are not a match pub fn arent_match(&self) -> bool { !self.are_match() } diff --git a/src/main.yml b/src/main.yml index ebdc1d0..1ea5339 100644 --- a/src/main.yml +++ b/src/main.yml @@ -1,5 +1,5 @@ name: imgeq -version: "0.0.2" +version: "0.1.0" author: https://github.com/michaelr0/imeq-rs settings: - ArgRequiredElseHelp