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

speciesnet/
lib.rs
