speciesnet/
lib.rs

1//! ## SpeciesNet Rust
2//!
3//! The home of the ensemble for running [SpeciesNet] models in Rust.
4//!
5//! ## Setup
6//!
7//! Run
8//!
9//! ```bash
10//! cargo add --git https://github.com/zubalis/speciesnet-rust.git --path speciesnet
11//! cargo add ort@=2.0.0-rc.9 -F download-binaries
12//! ```
13//!
14//! to your program to get the lastest version of speciesnet.
15//!
16//! ## Cargo features
17//!
18//! - `download-model`, enabled by default, this allows you to run [`SpeciesNet::new`] to
19//!   initialize the ensemble, which will download the default model from the internet.
20//!
21//! ## Model setup
22//!
23//! SpeciesNet Rust ensemble is using [ort] to run the model, which means the detector model and
24//! the classifier model needs to be converted to [ONNX] before this program can be run. We have a
25//! separate repository for generating SpeciesNet Rust compatible models in [zubalis/speciesnet-onnx].
26//! You can grab the model files from there, extract it to a directory and use
27//! [`SpeciesNet::from_model_folder`] to initialize the model from that folder.
28//!
29//! ## Examples
30//!
31//! Initializing speciesnet with a custom extracted model folder.
32//!
33//! ```rust,no_run
34//! use speciesnet::SpeciesNet;
35//!
36//! let speciesnet = SpeciesNet::from_model_folder("./speciesnet-v4a/")?;
37//! ```
38//!
39//! Running the entire pipeline (detector + classifier + ensemble).
40//!
41//! ```rust,no_run
42//! use std::path::PathBuf;
43//!
44//! use speciesnet::{SpeciesNet, Instance};
45//!
46//! let instances = vec![
47//!     Instance::from_path_buf(PathBuf::from("./img1.jpeg")),
48//!     Instance::from_path_buf(PathBuf::from("./img2.jpeg"))
49//! ];
50//!
51//! let speciesnet = SpeciesNet::new()?;
52//! let detections = speciesnet.predict(&instances)?;
53//! ```
54//!
55//! Running the detector pipeline.
56//!
57//! ```rust,no_run
58//! use std::path::PathBuf;
59//!
60//! use speciesnet::{SpeciesNet, Instance};
61//!
62//! let instances = vec![
63//!     Instance::from_path_buf(PathBuf::from("./img1.jpeg")),
64//!     Instance::from_path_buf(PathBuf::from("./img2.jpeg"))
65//! ];
66//!
67//! let speciesnet = SpeciesNet::new()?;
68//! let detections = speciesnet.detect(&instances)?;
69//! ```
70//!
71//! The returned detections is in the format of [Prediction] vector, which is the same for all
72//! apis.
73//!
74//! Running the classifier pipeline.
75//!  
76//! ```rust,no_run
77//! use std::path::PathBuf;
78//!
79//! use speciesnet::{SpeciesNet, Instance};
80//!
81//! let instances = vec![
82//!     Instance::from_path_buf(PathBuf::from("./img1.jpeg")),
83//!     Instance::from_path_buf(PathBuf::from("./img2.jpeg"))
84//! ];
85//!
86//! let speciesnet = SpeciesNet::new()?;
87//! let classifications = speciesnet.classify(&instances)?;
88//! ```
89//!
90//! Running the ensemble and geofence of the pipeline.
91//!
92//!  NOTE: This function differs from other functions where it operates on each instance of
93//! prediction, instead of taking the vector of predictions or instance like other API.
94//!
95//! ```rust,no_run
96//! use std::path::PathBuf;
97//!
98//! use speciesnet::{SpeciesNet, ClassificationBundle, BoundingBox, Category, Detection};
99//!
100//! let instances_json_path = "./instances.json";
101//! let detector_file_path = "./output_detector.json";
102//! let classifier_file_path = "./output_classifier.json";
103//!
104//! let speciesnet = SpeciesNet::new()?;
105//! let ensembles = speciesnet.ensemble(
106//!     instances_json_path,
107//!     detector_file_path,
108//!     classifier_file_path,
109//! )?;
110//! ```
111//!
112//! [SpeciesNet]: https://www.kaggle.com/models/google/speciesnet
113//! [Prediction]: speciesnet_core::io::Prediction
114//! [ONNX]: https://onnx.ai
115//! [zubalis/speciesnet-onnx]: https://github.com/zubalis/speciesnet-onnx
116//! [ort]: https://docs.rs/ort
117
118pub mod error;
119pub mod model_info;
120pub mod speciesnet;
121
122pub use speciesnet_core::{
123    classifier::{Classification, ClassificationBundle},
124    detector::{BoundingBox, Category, Detection},
125    ensemble::GeofenceResult,
126    io::{Instance, Instances, Prediction, Predictions},
127    load_image,
128    shape::Shape,
129};
130
131pub use speciesnet::SpeciesNet;
speciesnet/lib.rs

speciesnet/
lib.rs
