Wildlife Tools

https://wildlifedatasets.github.io/wildlife-tools/
Admin
The wildlife-tools library provides a simple interface for various tasks in the wildlife...
Tokens:12,898
Snippets:108
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install wildlife-tools using pip

Source: https://wildlifedatasets.github.io/wildlife-tools

Use this command to install the library directly from its GitHub repository using pip.

```bash
pip install git+https://github.com/WildlifeDatasets/wildlife-tools

```

--------------------------------

### Install wildlife-tools from cloned repository

Source: https://wildlifedatasets.github.io/wildlife-tools

Clone the repository and install the library in editable mode using pip. This is useful for development or when needing to modify the library's source code.

```bash
git clone git@github.com:WildlifeDatasets/wildlife-tools.git

cd wildlife-tools
pip install -e .

```

--------------------------------

### Initialize SimilarityPipeline with LightGlue

Source: https://wildlifedatasets.github.io/wildlife-tools/wildfusion

Sets up a SimilarityPipeline using LightGlue for matching with SuperPoint descriptors and keypoints. Scores are calibrated using isotonic regression. Fit the calibration before using the pipeline for scoring.

```python
import timm
import torchvision.transforms as T
from wildlife_tools.features import SuperPointExtractor
from wildlife_tools.similarity import MatchLightGlue

from wildlife_tools.similarity.wildfusion import SimilarityPipeline
from wildlife_tools.similarity.calibration import IsotonicCalibration


pipeline = SimilarityPipeline(
  matcher = MatchLightGlue(features='superpoint'),
  extractor = SuperPointExtractor(),
  transform = T.Compose([
      T.Resize([512, 512]),
      T.ToTensor()
  ]),
  calibration = IsotonicCalibration()
)
pipeline.fit_calibration(calibration_dataset1, calibration_dataset2)
scores = pipeline(query, database)
```

--------------------------------

### Initialize WildFusion with Multiple Similarity Pipelines

Source: https://wildlifedatasets.github.io/wildlife-tools/wildfusion

Configures WildFusion with a list of SimilarityPipeline instances, each potentially using different matchers, feature extractors, and calibration methods. Fit the calibration for all pipelines before using WildFusion for scoring.

```python
import timm
import torchvision.transforms as T
from wildlife_tools.features import *
from wildlife_tools.similarity import CosineSimilarity, MatchLOFTR, MatchLightGlue
from wildlife_tools.similarity.wildfusion import SimilarityPipeline, WildFusion
from wildlife_tools.similarity.calibration import IsotonicCalibration


matchers = [

    SimilarityPipeline(
        matcher = MatchLightGlue(features='superpoint'),
        extractor = SuperPointExtractor(),
        transform = T.Compose([
            T.Resize([512, 512]),
            T.ToTensor()
        ]),
        calibration = IsotonicCalibration()
    ),

    SimilarityPipeline(
        matcher = MatchLightGlue(features='aliked'),
        extractor = AlikedExtractor(),
        transform = T.Compose([
            T.Resize([512, 512]),
            T.ToTensor()
        ]),
        calibration = IsotonicCalibration()
    ),

    SimilarityPipeline(
        matcher = MatchLightGlue(features='disk'),
        extractor = DiskExtractor(),
        transform = T.Compose([
            T.Resize([512, 512]),
            T.ToTensor()
        ]),
        calibration = IsotonicCalibration()
    ),

    SimilarityPipeline(
        matcher = MatchLightGlue(features='sift'),
        extractor = SiftExtractor(),
        transform = T.Compose([
            T.Resize([512, 512]),
            T.ToTensor()
        ]),
        calibration = IsotonicCalibration()
    ),

    SimilarityPipeline(
        matcher = MatchLOFTR(pretrained='outdoor'),
        extractor = None,
        transform = T.Compose([
            T.Resize([512, 512]),
            T.Grayscale(),
            T.ToTensor(),
        ]),
        calibration = IsotonicCalibration()
    ),

    SimilarityPipeline(
        matcher = CosineSimilarity(),
        extractor = DeepFeatures(
            model = timm.create_model(
              'hf-hub:BVRA/wildlife-mega-L-384',
              num_classes=0,
              pretrained=True
              )
        ),
        transform = T.Compose([
            T.Resize(size=(384, 384)),
            T.ToTensor(),
            T.Normalize(mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225)),
        ]),
        calibration = IsotonicCalibration()
    ),
]

wildfusion = WildFusion(calibrated_matchers = matchers)
wildfusion.fit_calibration(calibration_dataset1, calibration_dataset2)
similarity = wildfusion(query, database)
```

--------------------------------

### Initialize DiskExtractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Instantiate the DiskExtractor for DISK keypoints and descriptors. It inherits from GlueFactoryExtractor and uses its configuration parameters.

```python
from wildlife.features.local import DiskExtractor

# Example usage:
# disk = DiskExtractor(force_num_keypoints=False, device='cuda')

```

--------------------------------

### Initialize GlueFactoryExtractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Instantiate the base GlueFactoryExtractor class with a configuration dictionary. Key parameters include max keypoints, detection threshold, and whether to force a specific number of keypoints.

```python
from wildlife.features.local import GlueFactoryExtractor

# Example configuration:
config = {
    "max_num_keypoints": 512,
    "detection_threshold": 0.0,
    "force_num_keypoints": True
}

# Example usage:
# extractor = GlueFactoryExtractor(config=config, device='cuda')

```

--------------------------------

### Initialize AlikedExtractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Instantiate the AlikedExtractor for ALIKED keypoints and descriptors. It inherits from GlueFactoryExtractor and uses its configuration parameters.

```python
from wildlife.features.local import AlikedExtractor

# Example usage:
# aliked = AlikedExtractor(max_num_keypoints=1024, device='cuda')

```

--------------------------------

### Initialize SiftExtractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Instantiate the SiftExtractor for SIFT keypoints and descriptors. It inherits from GlueFactoryExtractor and uses its configuration parameters, including the backend.

```python
from wildlife.features.local import SiftExtractor

# Example usage:
# sift = SiftExtractor(backend='opencv', device='cuda')

```

--------------------------------

### WildFusion with Shortlist and Score Budget

Source: https://wildlifedatasets.github.io/wildlife-tools/wildfusion

Utilizes WildFusion with a specified budget (B) for score calculations per query image, after constructing a shortlist using cosine similarity of MegaDescriptor features. Ensure calibration is fitted prior to execution.

```python
priority_matcher =  SimilarityPipeline(
    matcher = CosineSimilarity(),
    extractor = DeepFeatures(
        model = timm.create_model(
        'hf-hub:BVRA/wildlife-mega-L-384',
        num_classes=0,
        pretrained=True
        )
    ),
    transform = T.Compose([
        T.Resize(size=(384, 384)),
        T.ToTensor(),
        T.Normalize(mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225)),
    ]),
)

wildfusion = WildFusion(calibrated_matchers = matchers)
wildfusion.fit_calibration(calibration_dataset1, calibration_dataset2)
similarity = wildfusion(query, database, B=100)
```

--------------------------------

### BasicTrainer

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_training

Implements a basic training loop for PyTorch models. It supports reproducibility by including random states in checkpoints, allowing restarts from saved states.

```APIDOC
## BasicTrainer(dataset, model, objective, optimizer, epochs, scheduler=None, device='cuda', batch_size=128, num_workers=1, accumulation_steps=1, epoch_callback=None)

### Description
Implements basic training loop for Pytorch models. Checkpoints includes random states - any restarts from checkpoint preservers reproducibility.

### Parameters
#### Required Parameters
- **dataset** (ImageDataset) - Training dataset that gives (x, y) tensor pairs.
- **model** (Module) - Pytorch nn.Module for model / backbone.
- **objective** (Module) - Pytorch nn.Module for objective / loss function.
- **optimizer** (Optimizer) - Pytorch optimizer.
- **epochs** (int) - Number of training epochs.

#### Optional Parameters
- **scheduler** (Module) - Pytorch scheduler. Default: `None`
- **device** (str) - Device to be used for training. Default: `'cuda'`
- **batch_size** (int) - Training batch size. Default: `128`
- **num_workers** (int) - Number of data loading workers in torch DataLoader. Default: `1`
- **accumulation_steps** (int) - Number of gradient accumulation steps. Default: `1`
- **epoch_callback** (Callable) - Callback function to be called after each epoch. Default: `None`
```

--------------------------------

### WildFusion(calibrated_pipelines, priority_pipeline=None)

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Initializes WildFusion, which uses the mean of multiple calibrated SimilarityPipelines to calculate fused scores. It can be used with a limited computational budget by applying a fast-to-compute priority pipeline for shortlisting.

```APIDOC
### WildFusion(calibrated_pipelines, priority_pipeline=None)

#### Description
`WildFusion` uses the mean of multiple calibrated `SimilarityPipeline` to calculate fused scores. Since many local feature matching models require deep neural network inference for each query and database pair, the computation quickly becomes infeasible even for moderately sized datasets. WildFusion can be used with a limited computational budget by applying it only B times per query image. It uses a fast-to-compute similarity score (e.g., cosine similarity of deep features) provided by the priority_pipeline to construct a shortlist of the most promising matches for a given query. Final ranking is then based on WildFusion scores calculated for the pairs in the shortlist.

#### Parameters
- **calibrated_pipelines** (list[SimilarityPipeline]) - Required - List of SimilarityPipeline objects.
- **priority_pipeline** (SimilarityPipeline) - Optional - Fast-to-compute similarity matcher used for shortlisting.
```

--------------------------------

### Initialize SuperPointExtractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Instantiate the SuperPointExtractor for SuperPoint keypoints and descriptors. It inherits from GlueFactoryExtractor and uses its configuration parameters.

```python
from wildlife.features.local import SuperPointExtractor

# Example usage:
# superpoint = SuperPointExtractor(max_num_keypoints=512, device='cuda')

```

--------------------------------

### Split Dataset into Database and Query Sets

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Splits the dataset into training (database) and testing (query) subsets based on specified indices. This is useful for setting up inference scenarios.

```python
idx_train = list(range(10)) + list(range(190,200))
idx_test = list(range(10,20)) + list(range(200,210))
dataset_database = dataset.get_subset(idx_train)
dataset_query = dataset.get_subset(idx_test)
```

--------------------------------

### Extract Local Features with Aliked

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Initializes and uses the Aliked local feature extractor. Requires the 'cuda' device.

```python
from wildlife_tools.features import AlikedExtractor

device = 'cuda'

extractor = AlikedExtractor(device=device)
features = extractor(dataset)
```

--------------------------------

### MatchLOFTR

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Implements matching pairs using the LoFTR model correspondences, suitable for both outdoor and indoor scenes.

```APIDOC
## MatchLOFTR(pretrained='outdoor', init_threshold=0.2, device=None, apply_fine=False, **kwargs)

### Description
Implements matching pairs using LoFTR model correspondences. Introduced in: "LoFTR: Detector-Free Local Feature Matching with Transformers"

### Parameters
#### Path Parameters
- `pretrained` (str) - Optional - LOFTR model used. `outdoor` or `indoor`. Defaults to 'outdoor'.
- `init_threshold` (float) - Optional - Keep matches only over this threshold. Defaults to 0.2.
- `device` (str | None) - Optional - Specifies device used for the inference. Defaults to None.
- `apply_fine` (bool) - Optional - Use LoFTR fine refinement of keypoints locations. Has no effect on confidence, but is faster without fine refinement. False by default. Defaults to False.
```

--------------------------------

### Initialize ClipFeatures Extractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Instantiate the ClipFeatures class for extracting features using a CLIP model. Optionally provide a specific model and processor, or use defaults. Configure batch size, workers, device, and cache path.

```python
from wildlife.features.deep import ClipFeatures

# Example usage:
# clip_features = ClipFeatures(batch_size=32, device='cuda', cache_path='./clip_cache')

```

--------------------------------

### Extract Local Features with DISK

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Initializes and uses the DISK local feature extractor. Requires the 'cuda' device.

```python
from wildlife_tools.features import DiskExtractor

device = 'cuda'

extractor = DiskExtractor(device=device)
features = extractor(dataset)
```

--------------------------------

### MatchLightGlue

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Implements matching using the LightGlue model correspondences. This class is designed for local feature matching.

```APIDOC
## MatchLightGlue(features, init_threshold=0.1, device=None, **kwargs)

### Description
Implements matching using LightGlue model correspondences. Introduced in: "LightGlue: Local Feature Matching at Light Speed"

### Parameters
#### Path Parameters
- `features` (str) - Required - Features used for matching. Options: 'sift', 'superpoint', 'aliked', 'disk'. Must match extracted features from the dataset.
- `init_threshold` (float) - Optional - Keep matches only over this threshold. Matches with lower values are not passed to the collector. Defaults to 0.1.
- `device` (str) - Optional - Device used for inference. Defaults to None.
```

--------------------------------

### Calculate Similarity with MatchLightGlue and SuperPoint Features

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Uses `MatchLightGlue` with `SuperPointExtractor` to match pairs and `CollectCounts` to calculate similarity scores based on match counts at specified confidence thresholds. Ensure `T` (torchvision.transforms) is imported.

```python
from wildlife_tools.features import SuperPointExtractor
from wildlife_tools.similarity import MatchLightGlue, CollectCounts

transform = T.Compose([T.Resize([224, 224]), T.ToTensor()])
dataset_query.transform, dataset_database.transform = transform, transform
extractor = SuperPointExtractor()
matcher = MatchLightGlue(features='superpoint', collector=CollectCounts(thresholds=[0.25, 0.5, 0.75]))
output = matcher(extractor(dataset_query), extractor(dataset_database))
```

--------------------------------

### Load Dataset into Memory

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Use the DataToMemory class to load an entire dataset into memory for faster access. This is particularly useful for feature matching tasks like LOFTR where repeated disk I/O can be a bottleneck.

```python
from wildlife.features.memory import DataToMemory

# Assuming 'dataset' is an instance of FeatureDataset or similar
# memory_dataset = DataToMemory(dataset)

```

--------------------------------

### Load MacaqueFaces Dataset

Source: https://wildlifedatasets.github.io/wildlife-tools/training

Loads the MacaqueFaces dataset with specified transformations and label factorization. Ensure the 'data/MacaqueFaces' directory exists and contains the dataset.

```python
from wildlife_datasets.datasets import MacaqueFaces 
import torchvision.transforms as T

root = "data/MacaqueFaces"
transform = T.Compose([
    T.Resize([384, 384]),
    T.ToTensor(),
    T.Normalize(mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225))
])

MacaqueFaces.get_data(root)
dataset = MacaqueFaces(
    root,
    transform=transform,
    load_label=True,
    factorize_label=True,
)
```

--------------------------------

### Train Model with ArcFace Loss

Source: https://wildlifedatasets.github.io/wildlife-tools/training

Trains a model using a pre-trained backbone and ArcFace loss. Requires PyTorch, timm, and wildlife-tools. Ensure 'cuda' is available for device.

```python
import timm
import itertools
from torch.optim import SGD
from wildlife_tools.train import ArcFaceLoss, BasicTrainer
from wildlife_tools.train import set_seed

# Download MegaDescriptor-L backbone from HuggingFace Hub
backbone = timm.create_model('hf-hub:BVRA/MegaDescriptor-L-384', num_classes=0, pretrained=True)

# Arcface loss - needs backbone output size and number of classes.
embedding_size = backbone(dataset[0][0].unsqueeze(0)).size(1)
objective = ArcFaceLoss(
    num_classes=dataset.num_classes,
    embedding_size=embedding_size,
    margin=0.5,
    scale=64
    )

params = itertools.chain(backbone.parameters(), objective.parameters())
optimizer = SGD(params=params, lr=0.001, momentum=0.9)

trainer = BasicTrainer(
    dataset=dataset,
    model=backbone,
    objective=objective,
    optimizer=optimizer,
    epochs=1,
    batch_size=8,
    device='cuda',
)

trainer.train()
```

--------------------------------

### MatchPairs(batch_size=128, num_workers=0, tqdm_silent=False, collector=None)

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Base class for matching pairs from two datasets. Child classes must implement the `get_matches` method for processing batches of pairs.

```APIDOC
### MatchPairs(batch_size=128, num_workers=0, tqdm_silent=False, collector=None)

#### Description
Base class for matching pairs from two datasets. Any child class needs to implement `get_matches` method that implements processing of pair batches.

#### Parameters
- **batch_size** (int) - Optional - Number of pairs processed in one batch. Default: 128.
- **num_workers** (int) - Optional - Number of workers used for data loading. Default: 0.
- **tqdm_silent** (bool) - Optional - If True, progress bar is disabled. Default: False.
- **collector** (CollectCounts) - Optional - Collector object used for storing results. Default: None.
```

--------------------------------

### DiskExtractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Extracts DISK keypoints and descriptors. Based on the paper 'DISK: learning local features with policy gradient'.

```APIDOC
## DiskExtractor(detection_threshold=0.0, force_num_keypoints=True, max_num_keypoints=256, device=None, cache_path=None, **model_config)

### Description
DISK keypoints and descriptors.
* Paper: DISK: learning local features with policy gradient
* Link: https://arxiv.org/abs/2006.13566

### Parameters
#### Parameters
- **detection_threshold** (float) - Optional - Threshold for keypoints detection. Default: `0.0`
- **force_num_keypoints** (bool) - Optional - Force to return exactly max_num_keypoints keypoints. Default: `True`
- **max_num_keypoints** (int) - Optional - Maximum number of keypoints to return. Default: `256`
- **device** (str | None) - Optional - Select between cuda and cpu devices. Default: `None`
- **cache_path** (str) - Optional - Path for cached results. No caching for None. Default: `None`
- **model_config** (dict) - Optional - Additional model configuration parameters.
```

--------------------------------

### Calibrate Similarity Scores with IsotonicRegression

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Demonstrates fitting and predicting with `IsotonicCalibration` to map similarity scores to probabilities. This is a non-parametric approach useful for assessing calibration quality.

```python
from wildlife_tools.similarity.calibration import IsotonicCalibration

calibration = IsotonicCalibration()
calibration.fit([0, 0.5, 1], [0, 1, 1])
calibration.predict([0, 0.25, 0.8])
```

--------------------------------

### Extract Local Features with SuperPoint

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Initializes and uses the SuperPoint local feature extractor. Requires the 'cuda' device.

```python
from wildlife_tools.features import SuperPointExtractor

device = 'cuda'

extractor = SuperPointExtractor(device=device)
features = extractor(dataset)
```

--------------------------------

### fit_calibration (SimilarityPipeline)

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Fits the calibration model using two image datasets. This process considers all possible image pairs from both datasets and uses input similarity scores and binary ground truth labels.

```APIDOC
## fit_calibration(dataset0, dataset1)

### Description
Fit the calibration model using given two image datasets. Fitting the calibration model uses all possible pairs of images from the two datasets. Input scores are similarity scores calculated by the matcher. Binary input labels are based on ground truth labels (identity is the same or not).

### Parameters
#### Path Parameters
- **dataset0** (ImageDataset) - Required - The first dataset (e.g., part of training set).
- **dataset1** (ImageDataset) - Required - The second dataset (e.g., part of training set).
```

--------------------------------

### Citation for WildFusion Model

Source: https://wildlifedatasets.github.io/wildlife-tools

This is the citation information for the WildFusion model, as published on arXiv.

```bibtex
@article{cermak2024wildfusion,
  title={WildFusion: Individual animal identification with calibrated similarity fusion},
  author={Cermak, Vojt{\v{e}}ch and Picek, Lukas and Adam, Luk\'a\v{s} and Neumann, Luk\'a\v{s} and Matas, Ji{\v{r}}{\v{i}}},
  journal={arXiv preprint arXiv:2408.12934},
  year={2024}
}


```

--------------------------------

### Initialize DeepFeatures Extractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Instantiate the DeepFeatures class for extracting features using a PyTorch model. Specify batch size, number of workers, device, and an optional cache path.

```python
from wildlife.features.deep import DeepFeatures

# Example usage:
# deep_features = DeepFeatures(model=your_pytorch_model, batch_size=64, device='cuda')

```

--------------------------------

### fit_calibration (WildFusion)

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Fits all calibration models for all matchers within the `calibrated_pipelines` of the WildFusion object.

```APIDOC
## fit_calibration(dataset0, dataset1)

### Description
Fit the all calibration models for all matchers in `calibrated_pipelines`.

### Parameters
#### Path Parameters
- **dataset0** (ImageDataset) - Required - The first dataset (e.g., part of training set).
- **dataset1** (ImageDataset) - Required - The second dataset (e.g., part of training set).
```

--------------------------------

### Extract Local Features with SIFT

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Initializes and uses the SIFT local feature extractor. Requires the 'cuda' device.

```python
from wildlife_tools.features import SiftExtractor

device = 'cuda'

extractor = SiftExtractor(device=device)
features = extractor(dataset)
```

--------------------------------

### DataToMemory

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Loads a dataset into memory for faster access, which is particularly beneficial for feature extractors like LOFTR that require frequent image loading.

```APIDOC
## DataToMemory

### Description
Loads the dataset into memory for quicker access
Ideal for LOFTR, which operates directly on images, because loading images from storage can become a bottleneck when matching all query-database pairs, requiring n_query x n_database image loads.

### Method
#### __call__(dataset)

Loads data from input dataset into array and returns them as a new FeatureDataset.
```

--------------------------------

### CollectAll

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Collects results without additional processing, storing them as a list of matcher results for each pair. Useful for keypoint visualizations.

```APIDOC
## CollectAll(**kwargs)

### Description
Collect the results without additional processing. Collected data is list of matcher results for each pair. Usefull for keypoint visualizations.
```

--------------------------------

### __call__ (WildFusion)

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Computes fused similarity scores between two image datasets using multiple calibrated matchers. It supports a shortlist strategy to limit computation when a budget `B` is provided.

```APIDOC
## __call__(dataset0, dataset1, pairs=None, B=None, ignore_pairs=[])

### Description
Compute fused similarity scores between two images datasets using multiple calibrated matchers. WildFusion score is is calculated as mean of calibrated similarity scores. Optionally, to limit the number of pairs to compute, shortlist strategy to select the most promising pairs can be used.

### Parameters
#### Path Parameters
- **dataset0** (ImageDataset) - Required - The first dataset (e.g., query set).
- **dataset1** (ImageDataset) - Required - The second dataset (e.g., database set).
#### Query Parameters
- **pairs** (list of tuples) - Optional - Specific pairs of images to compute similarity scores. If None, compute similarity scores for all pairs. Is ignored if `B` is provided.
- **B** (int) - Optional - Number of pairs to compute similarity scores for. Required `priority_pipeline` to be assigned. If None, compute similarity scores for all pairs.
- **ignore_pairs** (list) - Optional - Pairs to ignore during computation.

### Returns
#### Success Response
- **score_combined** (ndarray) - 2D array of similarity scores between the query and database images. If `calibration` is provided, returns the calibrated similarity scores.
```

--------------------------------

### __call__ (SimilarityPipeline)

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Computes similarity scores between two image datasets, with optional calibration. It can compute scores for all pairs or a specific subset of pairs.

```APIDOC
## __call__(dataset0, dataset1, pairs=None)

### Description
Compute similarity scores between two image datasets, with optional calibration.

### Parameters
#### Path Parameters
- **dataset0** (ImageDataset) - Required - The first dataset (e.g., query set).
- **dataset1** (ImageDataset) - Required - The second dataset (e.g., database set).
#### Query Parameters
- **pairs** (list of tuples) - Optional - Specific pairs of images to compute similarity scores. If None, compute similarity scores for all pairs.

### Returns
#### Success Response
- **score_combined** (ndarray) - 2D array of similarity scores between the query and database images. If `calibration` is provided, return the calibrated similarity scores.
```

--------------------------------

### Calculate Similarity with MatchLOFTR

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Uses `MatchLOFTR` for descriptor-free matching directly on image pairs and `CollectCounts` to calculate similarity scores based on match counts at specified confidence thresholds. Ensure `T` (torchvision.transforms) is imported.

```python
from wildlife_tools.similarity import MatchLOFTR, CollectCounts

transform = T.Compose([T.Resize([224, 224]), T.Grayscale(), T.ToTensor()])
dataset_query.transform, dataset_database.transform = transform, transform
matcher = MatchLOFTR(collector=CollectCounts(thresholds=[0.25, 0.5, 0.75]))
output = matcher(dataset_query, dataset_database)
```

--------------------------------

### SimilarityPipeline

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Implements a pipeline for matching and calculating similarity scores between two image datasets.

```APIDOC
## SimilarityPipeline(matcher, extractor=None, calibration=None, transform=None)

### Description
Implements pipeline for matching and calculating similarity scores between two image datasets. Given two (query and database) image datasets, the pipeline consists of the following steps: 1. Apply image transforms. 2. Extract features for both datasets. 3. Compute similarity scores between query and database images. 4. Calibrate similarity scores.

### Parameters
- **matcher** (callable) - Required - A matcher that computes scores between two feature datasets.
- **extractor** (callable) - Optional - A function to extract features from the image datasets. Not needed for some matchers. Default: None
- **calibration** (callable) - Optional - A calibration model to refine similarity scores. Default: None
- **transform** (callable) - Optional - Image transformation function applied before feature extraction. Default: None
```

--------------------------------

### AlikedExtractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Extracts ALIKED keypoints and descriptors. Based on the paper 'ALIKED: A Lighter Keypoint and Descriptor Extraction Network via Deformable Transformation'.

```APIDOC
## AlikedExtractor(detection_threshold=0.0, force_num_keypoints=True, max_num_keypoints=256, device=None, cache_path=None, **model_config)

### Description
ALIKED keypoints and descriptors.
* Paper: ALIKED: A Lighter Keypoint and Descriptor Extraction Network via Deformable Transformation
* Link: https://arxiv.org/abs/2304.03608

### Parameters
#### Parameters
- **detection_threshold** (float) - Optional - Threshold for keypoints detection. Default: `0.0`
- **force_num_keypoints** (bool) - Optional - Force to return exactly max_num_keypoints keypoints. Default: `True`
- **max_num_keypoints** (int) - Optional - Maximum number of keypoints to return. Default: `256`
- **device** (str | None) - Optional - Select between cuda and cpu devices. Default: `None`
- **cache_path** (str) - Optional - Path for cached results. No caching for None. Default: `None`
- **model_config** (dict) - Optional - Additional model configuration parameters.
```

--------------------------------

### __call__

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Matches pairs of features from two feature datasets and processes the output using a collector.

```APIDOC
## __call__(dataset0, dataset1, pairs=None)

### Description
Match pairs of features from two feature datasets. Output for each pair is stored and processed using the collector.

### Parameters
#### Path Parameters
- `dataset0` (FeatureDataset) - Required - First dataset (e.g. query).
- `dataset1` (FeatureDataset) - Required - Second dataset (e.g. database).
- `pairs` (ndarray | None) - Optional - Numpy array with pairs of indexes. If None, all pairs are used. Defaults to None.

### Returns
#### Success Response
- `results` (dict) - Exact output is determined by the used collector.
```

--------------------------------

### get_matches

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Processes a batch and retrieves matches of pairs for that batch. This method is intended to be implemented by child classes.

```APIDOC
## get_matches(batch)

### Description
Process batch and get matches of pairs for the batch. Implemented in child classes.

### Parameters
#### Path Parameters
- `batch` (tuple) - Required - 4-tuple with indexes and data from PairDataset.

### Returns
#### Success Response
- `results` (List[dict]) - list of standardized dictionaries with keys: idx0, idx1, score, kpts0, kpts1. Length of list is equal to batch size.
```

--------------------------------

### SuperPointExtractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Extracts SuperPoint keypoints and descriptors. Based on the paper 'SuperPoint: Self-Supervised Interest Point Detection and Description'.

```APIDOC
## SuperPointExtractor(detection_threshold=0.0, force_num_keypoints=True, max_num_keypoints=256, device=None, cache_path=None, **model_config)

### Description
Superpoint keypoints and descriptors.
* Paper: SuperPoint: Self-Supervised Interest Point Detection and Description
* Link: https://arxiv.org/abs/1712.07629

### Parameters
#### Parameters
- **detection_threshold** (float) - Optional - Threshold for keypoints detection. Default: `0.0`
- **force_num_keypoints** (bool) - Optional - Force to return exactly max_num_keypoints keypoints. Default: `True`
- **max_num_keypoints** (int) - Optional - Maximum number of keypoints to return. Default: `256`
- **device** (str | None) - Optional - Select between cuda and cpu devices. Default: `None`
- **cache_path** (str) - Optional - Path for cached results. No caching for None. Default: `None`
- **model_config** (dict) - Optional - Additional model configuration parameters.
```

--------------------------------

### GlueFactoryExtractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Base class for Gluefactory extractors, providing common configuration for keypoint detection and feature extraction.

```APIDOC
## GlueFactoryExtractor(config, device=None, num_workers=1, cache_path=None)

### Description
Base class for Gluefactory extractors.
Common configuration of extractors:
1. max_num_keypoints: Maximum number of keypoints to return.
1. detection_threshold: Threshold for keypoints detection (use 0.0 if force_num_keypoints = True).
1. force_num_keypoints: Force to return exactly max_num_keypoints keypoints.

### Parameters
#### Parameters
- **config** (dict) - Required - Configuration dictionary for the model.
- **device** (str | None) - Optional - Select between cuda and cpu devices. Default: `None`
- **num_workers** (int) - Optional - Number of workers used for data loading. Default: `1`
- **cache_path** (str) - Optional - Path for cached results. No caching for None. Default: `None`
```

--------------------------------

### Extract Deep Features using MegaDescriptor

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Extracts deep features from a dataset using the MegaDescriptor model from timm. Requires 'cuda' device for optimal performance. Ensure the model is available via Hugging Face Hub.

```python
import timm
from wildlife_tools.features import DeepFeatures

model_name = "hf-hub:BVRA/MegaDescriptor-L-384"
backbone = timm.create_model(model_name, num_classes=0, pretrained=True)
extractor = DeepFeatures(backbone, batch_size=4, device='cuda')

query, database = extractor(dataset_query), extractor(dataset_database)
```

--------------------------------

### Extract Deep Features using Transformers

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Extracts deep features from a dataset using a pre-trained model from the Hugging Face Transformers library, such as MiewID-msv3. Requires 'cuda' device.

```python
from transformers import AutoModel
from wildlife_tools.features import DeepFeatures

backbone = AutoModel.from_pretrained('conservationxlabs/miewid-msv3', trust_remote_code=True)
extractor = DeepFeatures(backbone, device='cuda')
features = extractor(dataset)
```

--------------------------------

### IsotonicCalibration

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Performs isotonic regression calibration for ranking, using spline interpolation for a strictly increasing calibration curve.

```APIDOC
## IsotonicCalibration(interpolate=True, strict=True)

### Description
Performs isotonic regression calibration for ranking. Compared to standard isotonic regression, this implementation uses spline interpolation to ensure that the calibration curve is strictly increasing, which is necessary for ranking.

### Parameters
- **interpolate** (bool) - Optional - If True, use spline interpolation for calibration. Default: True
- **strict** (bool) - Optional - If True, apply strict adjustment to predictions. Default: True

### Methods
#### fit(scores, hits)
Fit the isotonic regression model to calibrate the scores.

##### Parameters
- **scores** (ndarray) - Required - Raw uncalibrated scores.
- **hits** (ndarray) - Required - Ground truth binary labels.

#### predict(scores)
Predict calibrated scores using a fitted calibration model.

##### Parameters
- **scores** (ndarray) - Required - Raw uncalibrated scores.

##### Returns
- **calibrated_scores** (ndarray) - Calibrated scores.
```

--------------------------------

### get_random_states

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_training

Retrieves the current random states from the trainer, which can be used to ensure reproducibility of training runs.

```APIDOC
## get_random_states()

### Description
Gives dictionary of random states for reproducibility.

### Method
GET (or similar, depending on SDK usage)

### Endpoint
(Not applicable for method-based calls, typically invoked on a trainer instance)

### Parameters
None
```

--------------------------------

### ClipFeatures

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Extracts features using the CLIP model. It uses raw images as input and supports custom models and processors.

```APIDOC
## ClipFeatures(model=None, processor=None, batch_size=128, num_workers=1, device='cpu', cache_path=None)

### Description
Extract features using CLIP model (https://arxiv.org/pdf/2103.00020.pdf). Uses raw images of input ImageDataset (i.e. dataset.transform = None)

### Parameters
#### Parameters
- **model** (CLIPModel) - Optional - Uses VIT-L backbone by default. Default: `None`
- **processor** (CLIPProcessor | None) - Optional - (CLIPProcessor, optional). Uses VIT-L processor by default. Default: `None`
- **batch_size** (int) - Optional - Batch size used for the feature extraction. Default: `128`
- **num_workers** (int) - Optional - Number of workers used for data loading. Default: `1`
- **device** (str) - Optional - Select between cuda and cpu devices. Default: `'cpu'`
- **cache_path** (str) - Optional - Path for cached results. No caching for None. Default: `None`
```

--------------------------------

### CosineSimilarity

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Wraps cosine similarity to be usable in SimilarityPipeline.

```APIDOC
## CosineSimilarity

### Description
Wraps cosine similarity to be usable in SimilarityPipeline.

### Methods
#### __call__(query, database, **kwargs)
Calculates cosine similarity given query and database feature datasets.

##### Parameters
- **query** (FeatureDataset) - Required - Query dataset of deep features.
- **database** (FeatureDataset) - Required - Database dataset of deep features.
- **kwargs** - Additional keyword arguments.

##### Returns
- **similarity** (ndarray) - 2D numpy array with cosine similarity.
```

--------------------------------

### SoftmaxLoss

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_training

A standard Cross-Entropy loss with a single dense layer for classification, suitable for typical classification problems.

```APIDOC
## SoftmaxLoss(num_classes, embedding_size)

### Description
CE with single dense layer classification head.

### Parameters
#### Required Parameters
- **num_classes** (int) - Number of classes.
- **embedding_size** (int) - Size of the input embeddings.
```

--------------------------------

### Citation for WildlifeDatasets Library

Source: https://wildlifedatasets.github.io/wildlife-tools

This is the citation information for the WildlifeDatasets library, as presented in the WACV 2024 proceedings.

```bibtex
@InProceedings{Cermak_2024_WACV,
    author    = {\v{C}erm\'ak, Vojt\v{e}ch and Picek, Luk\'a\v{s} and Adam, Luk\'a\v{s} and Papafitsoros, Kostas},
    title     = {{WildlifeDatasets: An Open-Source Toolkit for Animal Re-Identification}},
    booktitle = {Proceedings of the IEEE/CVF Winter Conference on Applications of Computer Vision (WACV)},
    month     = {January},
    year      = {2024},
    pages     = {5953-5963}
}


```

--------------------------------

### SiftExtractor

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Extracts SIFT keypoints and descriptors using a specified backend (e.g., OpenCV).

```APIDOC
## SiftExtractor(backend='opencv', detection_threshold=0.0, force_num_keypoints=True, max_num_keypoints=256, device=None, cache_path=None, **model_config)

### Description
SIFT keypoints and descriptors.

### Parameters
#### Parameters
- **backend** (str) - Optional - Specifies the backend to use for SIFT extraction (e.g., 'opencv'). Default: `'opencv'`
- **detection_threshold** (float) - Optional - Threshold for keypoints detection. Default: `0.0`
- **force_num_keypoints** (bool) - Optional - Force to return exactly max_num_keypoints keypoints. Default: `True`
- **max_num_keypoints** (int) - Optional - Maximum number of keypoints to return. Default: `256`
- **device** (str | None) - Optional - Select between cuda and cpu devices. Default: `None`
- **cache_path** (str) - Optional - Path for cached results. No caching for None. Default: `None`
- **model_config** (dict) - Optional - Additional model configuration parameters.
```

--------------------------------

### cosine_similarity

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Calculate cosine similarity between two sets of vectors. PyTorch Equivalent to `sklearn.metrics.pairwise.cosine_similarity`.

```APIDOC
## cosine_similarity(a, b)

### Description
Calculate cosine similarity between two sets of vectors. Pytorch Equivalent to `sklearn.metrics.pairwise.cosine_similarity`.

### Parameters
- **a** (ndarray) - Required - First set of vectors.
- **b** (ndarray) - Required - Second set of vectors.

### Returns
- **similarity** (ndarray) - 2D numpy array with cosine similarity.
```

--------------------------------

### CollectCounts

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Collects the count of significant matches based on provided confidence thresholds. Output is stored in an n_query x n_database grid.

```APIDOC
## CollectCounts(grid_dtype='float16', thresholds=(0.5,), **kwargs)

### Description
Collect count of significant matches given confidence thresholds. Output is stored in [n_query x n_database] grid. If multiple thresholds are provided, returns a dictionary with each threshold as a key and the corresponding grid as value.

### Parameters
#### Path Parameters
- `grid_dtype` (str) - Optional - Data type of the output grid. Defaults to 'float16'.
- `thresholds` (tuple) - Optional - Confidence thresholds for counting. Defaults to (0.5,).
```

--------------------------------

### Perform Inference with KnnClassifier

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Uses a K-Nearest Neighbors classifier with k=1 to predict labels based on cosine similarity scores. Evaluates accuracy against ground truth labels.

```python
import numpy as np
from wildlife_tools.inference import KnnClassifier

classifier = KnnClassifier(k=1, database_labels=dataset_database.labels_string)
predictions = classifier(similarity)
accuracy = np.mean(dataset_query.labels_string == predictions)
```

--------------------------------

### TripletLoss

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_training

Wraps PyTorch's Metric Learning TripletMarginLoss. This loss function is useful for tasks that involve learning embeddings where similar items are closer and dissimilar items are farther apart.

```APIDOC
## TripletLoss(margin=0.2, mining='semihard', distance='l2_squared')

### Description
Wraps Pytorch Metric Learning TripletMarginLoss.

### Parameters
#### Optional Parameters
- **margin** (int) - Margin for triplet loss. Default: `0.2`
- **mining** (str) - Type of triplet mining. One of: 'all', 'hard', 'semihard'. Default: `'semihard'`
- **distance** (str) - Distance metric for triplet loss. One of: 'cosine', 'l2', 'l2_squared'. Default: `'l2_squared'`
```

--------------------------------

### TopkClassifier

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_inference

Predicts the top k query labels given nearest matches in the database.

```APIDOC
## `TopkClassifier(database_labels, k=10, return_all=False)`

### Description
Predict top k query labels given nearest matches in the database.

### Parameters
#### Constructor Parameters
- **database_labels** (ndarray) - Required - Array containing the labels of the database.
- **k** (int) - Optional - The number of top predictions to return. Default: `10`
- **return_all** (bool) - Optional - Indicates whether to return scores along with predictions. Default: `False`

#### `__call__(similarity)`

### Description
Predicts the top k labels for each query based on the similarity matrix.

### Parameters
#### Call Parameters
- **similarity** (ndarray) - Required - A 2D similarity matrix with `n_query` x `n_database` shape.

### Returns
- **ndarray | tuple[ndarray, ndarray, ndarray]** - If `return_all` is False, single 2D array of shape `n_query` x `k`: preds (np.ndarray): The top k predicted labels for each query.
- **ndarray | tuple[ndarray, ndarray, ndarray]** - If `return_all` is True, tuple of three 2D arrays of shape `n_query` x `k`: preds (np.ndarray): The top k predicted labels for each query. scores (np.ndarray): The similarity scores corresponding to the top k predictions. idx (np.ndarray): The indices of the database entries corresponding to the top k predictions.
```

--------------------------------

### ArcFaceLoss

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_training

Wraps PyTorch's Metric Learning ArcFaceLoss. This loss function is suitable for classification tasks where angular margin is important.

```APIDOC
## ArcFaceLoss(num_classes, embedding_size, margin=0.5, scale=64)

### Description
Wraps Pytorch Metric Learning ArcFaceLoss.

### Parameters
#### Required Parameters
- **num_classes** (int) - Number of classes.
- **embedding_size** (int) - Size of the input embeddings.

#### Optional Parameters
- **margin** (int) - Margin for ArcFace loss (in radians). Default: `0.5`
- **scale** (int) - Scale parameter for ArcFace loss. Default: `64`
```

--------------------------------

### reliability_diagram

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_similarity

Calculates ECE (Expected calibration error) and plots the reliability diagram for a given set of scores and hits.

```APIDOC
## reliability_diagram(scores, hits, ax=None, skip_plot=False, num_bins=10, title='Reliability Diagram')

### Description
Calculates ECE (Expected calibration error) and plots reliability diagram for a given set of scores and hits.

### Parameters
- **scores** (ndarray) - Required - Raw uncalibrated scores.
- **hits** (ndarray) - Required - Ground truth binary labels.
- **ax** (Axes) - Optional - Axes to plot the diagram on. If None, a new figure is created. Default: None
- **skip_plot** (bool) - Optional - If True, only return ECE value. Default: False
- **num_bins** (int) - Optional - Number of bins to divide the scores into. Default: 10
- **title** (str) - Optional - Title of the plot. Default: 'Reliability Diagram'

### Returns
- **ece** (float) - Expected Calibration Error.
```

--------------------------------

### Calculate Cosine Similarity

Source: https://wildlifedatasets.github.io/wildlife-tools/inference

Calculates the cosine similarity between query and database feature vectors. The output is a matrix representing match scores.

```python
from wildlife_tools.similarity import CosineSimilarity

similarity_function = CosineSimilarity()
similarity = similarity_function(query, database)
```

--------------------------------

### DeepFeatures

Source: https://wildlifedatasets.github.io/wildlife-tools/reference_features

Extracts features using the forward pass of a PyTorch model. Supports caching for improved performance.

```APIDOC
## DeepFeatures(model, batch_size=128, num_workers=1, device='cpu', cache_path=None)

### Description
Extracts features using forward pass of pytorch model.

### Parameters
#### Parameters
- **model** (Module) - Required - Pytorch model used for the feature extraction.
- **batch_size** (int) - Optional - Batch size used for the feature extraction. Default: `128`
- **num_workers** (int) - Optional - Number of workers used for data loading. Default: `1`
- **device** (str) - Optional - Select between cuda and cpu devices. Default: `'cpu'`
- **cache_path** (str) - Optional - Path for cached results. No caching for None. Default: `None`
```
Tokens:
Raw