Skip to content

Commit cca6543

Browse files
VojtechCermakVojtechCermak
authored
Merge pull request #30 from WildlifeDatasets/dev
2 parents e6b7d11 + 5f24766 commit cca6543

40 files changed

+692
-654
lines changed

‎README.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,16 +28,21 @@
2828

2929
## Our other projects
3030

31-
| <a href="https://github.com/WildlifeDatasets/wildlife-datasets"><img src="https://github.com/WildlifeDatasets/wildlife-tools/raw/main/docs/resources/datasets-logo.png" alt="Wildlife datasets" width="200"></a> | <a href="https://huggingface.co/BVRA/MegaDescriptor-L-384"><img src="https://github.com/WildlifeDatasets/wildlife-tools/raw/main/docs/resources/megadescriptor-logo.png" alt="MegaDescriptor" width="200"></a> | <a href="https://github.com/WildlifeDatasets/wildlife-tools"><img src="https://github.com/WildlifeDatasets/wildlife-tools/raw/main/docs/resources/tools-logo.png" alt="Wildlife tools" width="200"></a> |
31+
| <a href="https://github.com/WildlifeDatasets/wildlife-datasets"><img src="https://github.com/WildlifeDatasets/wildlife-tools/raw/main/docs/resources/datasets-logo.png" alt="WildlifeDatasets" width="200"></a> | <a href="https://huggingface.co/BVRA/MegaDescriptor-L-384"><img src="https://github.com/WildlifeDatasets/wildlife-tools/raw/main/docs/resources/megadescriptor-logo.png" alt="MegaDescriptor" width="200"></a> | <a href="https://github.com/WildlifeDatasets/wildlife-tools"><img src="https://github.com/WildlifeDatasets/wildlife-tools/raw/main/docs/resources/wildlifereID10k-logo.png" alt="WildlifeReID-10k" width="200"></a> |
3232
|:--------------:|:-----------:|:------------:|
33-
| Datasets for identification of individual animals | Trained model for individual re&#x2011;identification | Tools for training re&#x2011;identification models |
33+
| Library for handling re&#x2011;identification datasets | Trained model for individual re&#x2011;identification | Dataset for identification of individual animals |
3434

3535
</br>
3636

3737
# Introduction
38-
The `wildlife-tools` library offers a simple interface for various tasks in the Wildlife Re-Identification domain. It covers use cases such as training, feature extraction, similarity calculation, image retrieval, and classification. It complements the `wildlife-datasets` library, which acts as dataset repository.
3938

40-
More information can be found in [Documentation](https://wildlifedatasets.github.io/wildlife-tools/)
39+
The `wildlife-tools` library offers a simple interface for various tasks in the wildlife re-identification domain. Its main features are:
40+
41+
- It covers use cases such as training, feature extraction, similarity calculation, image retrieval, and classification.
42+
- It provides traning codes and usage examples for our models [MegaDescriptor](./megadescriptor.md) and [WildFusion](./wildfusion.md).
43+
- It complements the [WildlifeDatasets](https://github.com/WildlifeDatasets/wildlife-datasets) library, which acts as dataset repository.
44+
45+
More information can be found in the [documentation](https://wildlifedatasets.github.io/wildlife-tools/).
4146

4247
## What's New
4348
Here’s a summary of recent updates and changes.

‎docs/dataset.md‎

Lines changed: 0 additions & 57 deletions
This file was deleted.

‎docs/features.md‎

Lines changed: 0 additions & 46 deletions
This file was deleted.

‎docs/figures/loading_methods.png‎

-142 KB
Binary file not shown.

‎docs/index.md‎

Lines changed: 11 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,22 @@
1-
<p align="center">
2-
<a href="https://github.com/WildlifeDatasets/wildlife-tools/issues"><img src="https://img.shields.io/github/issues/WildlifeDatasets/wildlife-tools" alt="GitHub issues"></a>
3-
<a href="https://github.com/WildlifeDatasets/wildlife-tools/pulls"><img src="https://img.shields.io/github/issues-pr/WildlifeDatasets/wildlife-tools" alt="GitHub pull requests"></a>
4-
<a href="https://github.com/WildlifeDatasets/wildlife-tools/graphs/contributors"><img src="https://img.shields.io/github/contributors/WildlifeDatasets/wildlife-tools" alt="GitHub contributors"></a>
5-
<a href="https://github.com/WildlifeDatasets/wildlife-tools/network/members"><img src="https://img.shields.io/github/forks/WildlifeDatasets/wildlife-tools" alt="GitHub forks"></a>
6-
<a href="https://github.com/WildlifeDatasets/wildlife-tools/stargazers"><img src="https://img.shields.io/github/stars/WildlifeDatasets/wildlife-tools" alt="GitHub stars"></a>
7-
<a href="https://github.com/WildlifeDatasets/wildlife-tools/watchers"><img src="https://img.shields.io/github/watchers/WildlifeDatasets/wildlife-tools" alt="GitHub watchers"></a>
8-
<a href="https://github.com/WildlifeDatasets/wildlife-tools/blob/main/LICENSE"><img src="https://img.shields.io/github/license/WildlifeDatasets/wildlife-tools" alt="License"></a>
9-
</p>
10-
11-
<div align="center">
12-
<img src="resources/tools-logo.png" alt="Wildlife tools" width="300">
13-
<p align="center">A toolkit for Animal Individual Identification that covers use cases such as training, feature extraction, similarity calculation, image retrieval, and classification.</p>
14-
<a href="https://wildlifedatasets.github.io/wildlife-tools/">Documentation</a>
15-
·
16-
<a href="https://github.com/WildlifeDatasets/wildlife-tools/issues/new?assignees=aerodynamic-sauce-pan&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D">Report Bug</a>
17-
·
18-
<a href="https://github.com/WildlifeDatasets/wildlife-tools/issues/new?assignees=aerodynamic-sauce-pan&labels=enhancement&projects=&template=enhancement.md&title=%5BEnhancement%5D">Request Feature</a>
19-
</div>
20-
21-
</br >
22-
23-
## Our other projects
24-
25-
26-
<div align="center">
27-
<div style="display: flex; justify-content: center">
28-
<div style="margin-right: 50px;">
29-
<img src="resources/megadescriptor-logo.png" alt="Image 1" width="200" style="margin-bottom: 5px;">
30-
<p><a href="https://huggingface.co/BVRA/MegaDescriptor-L-384">MegaDescriptor</a></p>
31-
</div>
32-
33-
<div>
34-
<img src="resources/datasets-logo.png" alt="Image 2" width="200" style="margin-bottom: 5px;"> <!-- Adjust margin as needed -->
35-
<p><a href="https://github.com/WildlifeDatasets/wildlife-datasets" >Wildlife Datasets</a></p>
36-
</div>
37-
</div>
38-
</div>
39-
40-
41-
<h1></h1>
42-
431
# Introduction
44-
The `wildlife-tools` library offers a simple interface for various tasks in the Wildlife Re-Identification domain. It covers use cases such as training, feature extraction, similarity calculation, image retrieval, and classification. It complements the `wildlife-datasets` library, which acts as dataset repository.
45-
46-
More information can be found in [Documentation](https://wildlifedatasets.github.io/wildlife-tools/)
472

48-
## What's New
49-
Here’s a summary of recent updates and changes.
3+
The `wildlife-tools` library offers a simple interface for various tasks in the wildlife re-identification domain. Its main features are:
504

51-
52-
- **Expanded Functionality:** Local feature matching is done using [gluefactory](https://github.com/cvg/glue-factory)
53-
- Feature extraction methods: SuperPoint, ALIKED, DISK, SIFT features
54-
- Matching method: LightGlue, More efficient LoFTR
55-
- **New Feature:** Introduced WildFusion, calibrated score fusion for high-accuracy animal reidentification. Added calibration methods.
56-
- **Bug Fixes:** Resolved issues with knn and ranking inference methods and many more.
5+
- It covers use cases such as training, feature extraction, similarity calculation, image retrieval, and classification.
6+
- It provides traning codes and usage examples for our models [MegaDescriptor](./megadescriptor.md) and [WildFusion](./wildfusion.md).
7+
- It complements the [WildlifeDatasets](https://github.com/WildlifeDatasets/wildlife-datasets) library, which acts as dataset repository.
578

589

5910
## Installation
6011

61-
To install `wildlife-tools`, you can build it from scratch or use pre-build Pypi package.
62-
63-
64-
### Using Pypi
12+
Install `wildlife-tools` using `pip`
6513

6614
```script
67-
pip install wildlife-tools
15+
pip install git+https://github.com/WildlifeDatasets/wildlife-tools
6816
```
6917

70-
### Building from scratch
18+
or clone the repository using `git` and install it.
7119

72-
Clone the repository using `git` and install it.
7320
```script
7421
git clone git@github.com:WildlifeDatasets/wildlife-tools.git
7522
@@ -80,15 +27,15 @@ pip install -e .
8027

8128
## Modules in the in the `wildlife-tools`
8229

83-
- The `data` module provides tools for creating instances of the `ImageDataset`.
84-
- The `train` module offers tools for fine-tuning feature extractors on the `ImageDataset`.
85-
- The `features` module provides tools for extracting features from the `ImageDataset` using various extractors.
30+
- The `data` module provides tools for creating instances of datasets.
31+
- The `train` module offers tools for fine-tuning feature extractors.
32+
- The `features` module provides tools for extracting features using various extractors.
8633
- The `similarity` module provides tools for constructing a similarity matrix from query and database features.
8734
- The `inference` module offers tools for creating predictions using the similarity matrix.
8835

8936

9037

91-
## Relations between modules:
38+
## Relations between modules
9239

9340
```mermaid
9441
graph TD;
@@ -99,64 +46,6 @@ pip install -e .
9946
D-->|similarity matrix|E[Inference]
10047
```
10148

102-
103-
104-
## Example
105-
### 1. Create `ImageDataset`
106-
Using metadata from `wildlife-datasets`, create `ImageDataset` object for the MacaqueFaces dataset.
107-
108-
```Python
109-
from wildlife_datasets.datasets import MacaqueFaces
110-
from wildlife_tools.data import ImageDataset
111-
import torchvision.transforms as T
112-
113-
metadata = MacaqueFaces('datasets/MacaqueFaces')
114-
transform = T.Compose([T.Resize([224, 224]), T.ToTensor(), T.Normalize(mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225))])
115-
dataset = ImageDataset(metadata.df, metadata.root, transform=transform)
116-
```
117-
118-
Optionally, split metadata into subsets. In this example, query is first 100 images and rest are in database.
119-
120-
```Python
121-
dataset_database = ImageDataset(metadata.df.iloc[100:,:], metadata.root, transform=transform)
122-
dataset_query = ImageDataset(metadata.df.iloc[:100,:], metadata.root, transform=transform)
123-
```
124-
125-
### 2. Extract features
126-
Extract features using MegaDescriptor Tiny, downloaded from HuggingFace hub.
127-
128-
```Python
129-
import timm
130-
from wildlife_tools.features import DeepFeatures
131-
132-
name = 'hf-hub:BVRA/MegaDescriptor-T-224'
133-
extractor = DeepFeatures(timm.create_model(name, num_classes=0, pretrained=True))
134-
query, database = extractor(dataset_query), extractor(dataset_database)
135-
```
136-
137-
### 3. Calculate similarity
138-
Calculate cosine similarity between query and database deep features.
139-
140-
```Python
141-
from wildlife_tools.similarity import CosineSimilarity
142-
143-
similarity_function = CosineSimilarity()
144-
similarity = similarity_function(query, database)
145-
```
146-
147-
148-
### 4. Evaluate
149-
Use the cosine similarity in nearest neigbour classifier and get predictions.
150-
151-
```Python
152-
import numpy as np
153-
from wildlife_tools.inference import KnnClassifier
154-
155-
classifier = KnnClassifier(k=1, database_labels=dataset_database.labels_string)
156-
predictions = classifier(similarity)
157-
accuracy = np.mean(dataset_query.labels_string == predictions)
158-
```
159-
16049
## Citation
16150

16251
If you like our package, please cite us.

0 commit comments

Comments
 (0)