LoFTR

https://docs.rs/loftr
Admin
Native Rust/tch LoFTR feature matching crate exposing a high-level API for constructing models,...
Tokens:84,680
Snippets:758
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### LoFTR Model Usage Example

Source: https://docs.rs/loftr/latest/src/loftr/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to initialize a LoFTR model, load weights, and perform feature matching between two images. This example requires the 'doc-only' feature to be disabled for local runs and assumes libtorch is available or the 'download-libtorch' feature is enabled.

```rust
use loftr::{LoftrConfig, LoftrModel};
use tch::{Device, Kind, Tensor};

let mut model = LoftrModel::new(Device::Cpu, LoftrConfig::outdoor())?;
model.load_weights("artifacts/weights/loftr_outdoor_state_dict.safetensors")?;

let image0 = Tensor::rand([1, 1, 128, 128], (Kind::Float, Device::Cpu));
let image1 = Tensor::rand([1, 1, 128, 128], (Kind::Float, Device::Cpu));
let matches = model.forward(&image0, &image1)?;

println!("match count = {}", matches.confidence.size()[0]);
# Ok::<(), loftr::LoftrError>(())
```

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

### LoftrConfig Presets

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrConfig.html?search=std%3A%3Avec

Provides access to predefined configurations for the LoFTR model. Users can start with a default configuration and customize it as needed.

```APIDOC
## LoftrConfig Presets

### `LoftrConfig::outdoor()`

Returns the default outdoor `LoFTR` preset used by this crate. This is also the `Default` configuration.

### `LoftrConfig::indoor()`

Returns the legacy indoor `LoFTR` preset used by Kornia’s shared fixtures.

### `LoftrConfig::indoor_new()`

Returns the indoor `LoFTR` preset with Kornia’s temperature fix enabled.
```

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

### Any::type_id Method

Source: https://docs.rs/loftr/latest/loftr/enum.BackboneType.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Gets the `TypeId` of `self` for the `Any` trait.

```rust
fn type_id(&self) -> TypeId
```

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

### LoftrModel::new

Source: https://docs.rs/loftr/latest/index.html

Constructs a new LoFTR model instance with a specified device and configuration. This is the entry point for initializing the LoFTR model.

```APIDOC
## LoftrModel::new

### Description
Constructs a new `LoFTR` model instance with a specified device and configuration. This is the entry point for initializing the LoFTR model.

### Method
Associated function (constructor)

### Parameters
* **device** (`tch::Device`) - The device on which to run the model (e.g., CPU, CUDA).
* **config** (`LoftrConfig`) - The configuration for the LoFTR model, specifying architecture details.

### Returns
* `Result<LoftrModel, LoftrError>` - A `LoftrModel` instance on success, or a `LoftrError` on failure.
```

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

### Initialize FinePreprocess

Source: https://docs.rs/loftr/latest/src/loftr/fine_preprocess.rs.html?search=u32+-%3E+bool

Constructs a new FinePreprocess instance. Validates the fine window size and initializes optional linear layers if coarse feature concatenation is enabled.

```rust
impl FinePreprocess {
    pub fn new(vs: &nn::Path<'_>, config: &LoftrConfig) -> Result<Self, LoftrError> {
        if config.fine_window_size <= 0 || config.fine_window_size % 2 == 0 {
            return Err(LoftrError::InvalidConfig(format!(
                "FinePreprocess requires a positive odd fine_window_size; got {}",
                config.fine_window_size
            )));
        }

        let d_model_c = config.coarse.d_model;
        let d_model_f = config.fine.d_model;
        let linear_config = nn::LinearConfig {
            ws_init: nn::init::DEFAULT_KAIMING_NORMAL,
            ..Default::default()
        };

        let (down_proj, merge_feat) = if config.fine_concat_coarse_feat {
            let down_proj = nn::linear(vs / "down_proj", d_model_c, d_model_f, linear_config);
            let merge_feat = nn::linear(vs / "merge_feat", 2 * d_model_f, d_model_f, linear_config);
            (Some(down_proj), Some(merge_feat))
        } else {
            (None, None)
        };

        Ok(Self {
            cat_coarse_feat: config.fine_concat_coarse_feat,
            window_size: config.fine_window_size,
            d_model_f,
            down_proj,
            merge_feat,
        })
    }
// ... forward method
}

```

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

### Get First Dimension of a Tensor

Source: https://docs.rs/loftr/latest/src/loftr/fine_preprocess.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the size of the first dimension of a tensor. This function validates that the tensor is rank-1 before returning its size.

```rust
fn first_dim(tensor: &Tensor, label: &str) -> Result<i64, LoftrError> {
    let dims = tensor.size();
    if dims.len() != 1 {
        return Err(LoftrError::InvalidConfig(format!(
            "FinePreprocessData `{label}` must be rank-1; got {dims:?}"
        )));
    }
    Ok(dims[0])
}
```

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

### Basic LoFTR Model Usage

Source: https://docs.rs/loftr/latest/index.html

Demonstrates the typical workflow for using the LoFTR model: initializing the model, loading weights, and performing a forward pass to match features between two images. Ensure you have the correct weights file path.

```rust
use loftr::{LoftrConfig, LoftrModel};
use tch::{Device, Kind, Tensor};

let mut model = LoftrModel::new(Device::Cpu, LoftrConfig::outdoor())?;
model.load_weights("artifacts/weights/loftr_outdoor_state_dict.safetensors")?;

let image0 = Tensor::rand([1, 1, 128, 128], (Kind::Float, Device::Cpu));
let image1 = Tensor::rand([1, 1, 128, 128], (Kind::Float, Device::Cpu));
let matches = model.forward(&image0, &image1)?;

println!("match count = {}", matches.confidence.size()[0]);

```

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

### LoFTR Encoder Layer Initialization

Source: https://docs.rs/loftr/latest/src/loftr/transformer.rs.html?search=std%3A%3Avec

Initializes a vector of LoFTR encoder layers based on the provided configuration. This is used during the setup of the transformer model.

```rust
let mut encoder_layers = Vec::with_capacity(config.layers.len());
        for (index, _) in config.layers.iter().enumerate() {
            encoder_layers.push(LoFTREncoderLayer::new(
                &(vs / "layers" / index.to_string()),
                config.d_model,
                config.nhead,
                config.attention,
            )?);
        }

        Ok(Self {
            d_model: config.d_model,
            layer_types: config.layers.clone(),
            layers: encoder_layers,
        })
```

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

### From and Into Implementations

Source: https://docs.rs/loftr/latest/loftr/struct.MatchCoarseConfig.html

Enables conversion to and from `MatchCoarseConfig` types, simplifying data transformations.

```rust
fn from(t: T) -> T
```

```rust
fn into(self) -> U
```

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

### Error::description Method (Deprecated)

Source: https://docs.rs/loftr/latest/loftr/enum.LoftrError.html

Deprecated method for getting an error description. Prefer using the Display implementation or `to_string()` for formatted error messages.

```rust
fn description(&self) -> &str
```

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

### Indoor LoFTR Configuration with Temperature Fix

Source: https://docs.rs/loftr/latest/src/loftr/loftr_config.rs.html?search=

Returns the indoor LoFTR preset with Kornia's temperature fix enabled for the coarse matching module.

```rust
/// Returns the indoor `LoFTR` preset with Kornia's temperature fix enabled.
    #[must_use]
    pub fn indoor_new() -> Self {
        let mut config = Self::indoor();
        config.coarse.temp_bug_fix = true;
        config
    }
```

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

### Convert Indices to Coarse Points

Source: https://docs.rs/loftr/latest/src/loftr/coarse_matching.rs.html?search=

Transforms flattened match indices into 2D coordinates (x, y) and scales them. This is used to get the actual pixel locations of matches.

```rust
fn coarse_points(indices: &Tensor, width: i64, scale: Tensor) -> Tensor {
    let indices = indices.to_kind(Kind::Int64);
    let x = indices.remainder(width).to_kind(Kind::Float);
    let y = indices.floor_divide_scalar(width).to_kind(Kind::Float);
    Tensor::stack(&[x, y], 1) * scale
}
```

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

### LoFTRModel::new

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrModel.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Builds a LoFTR model on the requested device. Initializes the model with allocated parameters but without loaded weights.

```APIDOC
## LoFTRModel::new

### Description
Builds a `LoFTR` model on the requested device. Initializes the model with allocated parameters but without loaded weights.

### Method
`pub fn new(device: Device, config: LoftrConfig) -> Result<Self, LoftrError>`

### Arguments
* `device` - Device where model parameters and inference tensors will live.
* `config` - High-level `LoFTR` configuration preset or override set.

### Returns
A constructed model with allocated parameters but no loaded weights yet.

### Errors
Returns an error when the model configuration is invalid or one of the internal modules cannot be constructed.
```

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

### Get Mutable VarStore Reference

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrModel.html

Returns a mutable reference to the underlying `tch` variable store. Intended for advanced integrations requiring direct access to parameter storage.

```rust
pub fn var_store_mut(&mut self) -> &mut VarStore
```

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

### Legacy Indoor LoFTR Configuration

Source: https://docs.rs/loftr/latest/src/loftr/loftr_config.rs.html?search=

Returns the legacy indoor LoFTR preset, which is identical to the outdoor configuration in this implementation.

```rust
/// Returns the legacy indoor `LoFTR` preset used by Kornia's shared fixtures.
    #[must_use]
    pub fn indoor() -> Self {
        Self::outdoor()
    }
```

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

### Get Immutable VarStore Reference

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrModel.html

Returns an immutable reference to the underlying `tch` variable store. Useful for inspecting loaded parameters or integrating with external `tch` helpers.

```rust
pub fn var_store(&self) -> &VarStore
```

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

### CoarseMatching Initialization

Source: https://docs.rs/loftr/latest/src/loftr/coarse_matching.rs.html?search=u32+-%3E+bool

Initializes CoarseMatching with DualSoftmax configuration. Clones the configuration for internal use.

```rust
pub fn new(config: &MatchCoarseConfig) -> Self {
        match config.match_type {
            MatchType::DualSoftmax => Self {
                config: config.clone(),
            },
        }
    }
```

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

### High-Level LoFTR Model Configuration

Source: https://docs.rs/loftr/latest/src/loftr/loftr_config.rs.html

The main configuration struct for the LoFTR model, combining backbone, resolution, transformer, and matching parameters. Use `LoftrConfig::outdoor()` as a starting point.

```rust
/// High-level `LoFTR` model configuration.
///
/// Most users should start from [`LoftrConfig::outdoor`] and only override
/// fields when matching a known reference setup.
#[derive(Debug, Clone, PartialEq)]
pub struct LoftrConfig {
    /// Backbone implementation to use.
    pub backbone_type: BackboneType,
    /// Output stride pair `(coarse_stride, fine_stride)`.
    pub resolution: (i64, i64),
    /// Fine-stage local window size in feature-grid cells.
    pub fine_window_size: i64,
    /// Whether fine matching concatenates coarse token features before projection.
    pub fine_concat_coarse_feat: bool,
    /// ResNet-FPN backbone parameters.
    pub resnetfpn: ResNetFpnConfig,
    /// Coarse transformer parameters.
    pub coarse: TransformerConfig,
    /// Coarse matching parameters.
    pub match_coarse: MatchCoarseConfig,
    /// Fine transformer parameters.
    pub fine: FineConfig,
}

impl LoftrConfig {
    /// Returns the default outdoor `LoFTR` preset used by this crate.
    ///
    /// This is also the [`Default`] configuration.
    #[must_use]
    pub fn outdoor() -> Self {
        Self {
            backbone_type: BackboneType::ResNetFpn,

```

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

### Build LoftrModel Instance

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrModel.html

Constructs a new LoFTR model instance on the specified device with the given configuration. Use this to initialize the model before loading weights.

```rust
pub fn new(device: Device, config: LoftrConfig) -> Result<Self, LoftrError>
```

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

### FullAttention::forward

Source: https://docs.rs/loftr/latest/src/loftr/linear_attention.rs.html

Computes attention using a standard full attention mechanism. It calculates the dot product of queries and keys, applies masking, and then uses softmax to get attention weights. Dropout can be optionally applied.

```APIDOC
## FullAttention::forward

### Description
Computes attention using a standard full attention mechanism. It calculates the dot product of queries and keys, applies masking, and then uses softmax to get attention weights. Dropout can be optionally applied.

### Method
`forward`

### Parameters
- `queries`: Tensor representing query vectors.
- `keys`: Tensor representing key vectors.
- `values`: Tensor representing value vectors.
- `q_mask`: Optional mask for queries.
- `kv_mask`: Optional mask for key-value pairs.

### Returns
- `Result<Tensor, LoftrError>`: The resulting attention tensor or an error.

### Notes
- The input tensors are expected to have a shape of [N, L, H, D] for queries and [N, S, H, D] for keys and values, where N is batch size, L is sequence length, S is key/value sequence length, H is number of heads, and D is head dimension.
- `softmax_temp` is calculated based on the head dimension for scaling.
- `use_dropout` and `attention_dropout` control the application of dropout to the attention weights.
```

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

### LoFTRConfig Indoor Preset with Temperature Fix

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrConfig.html

Returns the indoor LoFTR preset with Kornia's temperature fix enabled.

```rust
pub fn indoor_new() -> Self
```

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

### LoFTRConfig Legacy Indoor Preset

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrConfig.html

Returns the legacy indoor LoFTR preset, as used in Kornia's shared fixtures.

```rust
pub fn indoor() -> Self
```

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

### ResNetFpn8_2 Backbone Initialization

Source: https://docs.rs/loftr/latest/src/loftr/backbone.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes the ResNetFpn8_2 backbone with specified configuration. Includes validation for input dimensions to ensure they are positive.

```rust
#[derive(Debug)]
pub struct ResNetFpn8_2 {
    conv1: nn::Conv2D,
    bn1: nn::BatchNorm,
    layer1: ResNetLayer,
    layer2: ResNetLayer,
    layer3: ResNetLayer,
    layer3_outconv: nn::Conv2D,
    layer2_outconv: nn::Conv2D,
    layer2_outconv2: FpnHead,
    layer1_outconv: nn::Conv2D,
    layer1_outconv2: FpnHead,
}

impl ResNetFpn8_2 {
    pub fn new(vs: &nn::Path<'_>, config: &ResNetFpnConfig) -> Result<Self, LoftrError> {
        let initial_dim = config.initial_dim;
        let block_dims = config.block_dims;
        if initial_dim <= 0 || block_dims.iter().any(|dim| *dim <= 0) {
            return Err(LoftrError::InvalidConfig(format!(
                "ResNetFpn8_2 requires positive dimensions; got initial_dim={initial_dim}, block_dims={block_dims:?}"
            )));
        }

        let conv1 = nn::conv2d(
            &(vs / "conv1"),
            1,
            initial_dim,
            7,
            nn::ConvConfig {
                stride: 2,
                padding: 3,
                bias: false,
                ..Default::default()
            },
        );

```

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

### LoFTRModel::new

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrModel.html?search=

Constructs a new LoFTRModel instance on the specified device with the given configuration. Weights are not loaded by this method.

```APIDOC
## LoftrModel::new

### Description
Builds a `LoFTR` model on the requested device.

### Method
`pub fn new(device: Device, config: LoftrConfig) -> Result<Self, LoftrError>`

### Arguments
* `device` - Device where model parameters and inference tensors will live.
* `config` - High-level `LoFTR` configuration preset or override set.

### Returns
A constructed model with allocated parameters but no loaded weights yet.

### Errors
Returns an error when the model configuration is invalid or one of the internal modules cannot be constructed.
```

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

### LoFTR Indoor New Configuration with Temperature Fix

Source: https://docs.rs/loftr/latest/src/loftr/loftr_config.rs.html

Returns an indoor LoFTR preset with Kornia's temperature fix enabled. This modifies the coarse matching configuration to enable the temperature bug fix.

```rust
pub fn indoor_new() -> Self {
        let mut config = Self::indoor();
        config.coarse.temp_bug_fix = true;
        config
    }
```

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

### LoFTRModel::new Constructor

Source: https://docs.rs/loftr/latest/src/loftr/loftr_model.rs.html?search=std%3A%3Avec

Constructs a LoFTR model instance on the specified device with the given configuration. Initializes all internal modules and allocates parameters.

```rust
pub fn new(device: Device, config: LoftrConfig) -> Result<Self, LoftrError> {
    let var_store = nn::VarStore::new(device);
    let root = var_store.root();
    let backbone = build_backbone(&root, &config)?;
    let pos_encoding = PositionEncodingSine::new(
        config.coarse.d_model,
        (256, 256),
        config.coarse.temp_bug_fix,
        device,
    )?;
    let loftr_coarse =
        LocalFeatureTransformer::new(&(root.clone() / "loftr_coarse"), &config.coarse)?;
    let coarse_matching = CoarseMatching::new(&config.match_coarse);
    let fine_preprocess = FinePreprocess::new(&(root.clone() / "fine_preprocess"), &config)?;
    let fine_transformer_config = crate::loftr_config::TransformerConfig {
        d_model: config.fine.d_model,
        d_ffn: config.fine.d_ffn,
        nhead: config.fine.nhead,
        layers: config.fine.layers.clone(),
        attention: config.fine.attention,
        temp_bug_fix: false,
    };
    let loftr_fine =
        LocalFeatureTransformer::new(&(root / "loftr_fine"), &fine_transformer_config)?;
    Ok(Self {
        config,
        var_store,
        backbone,
        pos_encoding,
        loftr_coarse,
        coarse_matching,
        fine_preprocess,
        loftr_fine,
    })
}
```

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

### LoftrConfig Presets

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrConfig.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides methods to retrieve default LoFTR configurations for different scenarios. These presets allow users to quickly initialize the LoFTR model with common settings.

```APIDOC
## LoftrConfig

High-level `LoFTR` model configuration. Most users should start from `LoftrConfig::outdoor` and only override fields when matching a known reference setup.

### Fields

*   `backbone_type: BackboneType` - Backbone implementation to use.
*   `resolution: (i64, i64)` - Output stride pair `(coarse_stride, fine_stride)`.
*   `fine_window_size: i64` - Fine-stage local window size in feature-grid cells.
*   `fine_concat_coarse_feat: bool` - Whether fine matching concatenates coarse token features before projection.
*   `resnetfpn: ResNetFpnConfig` - ResNet-FPN backbone parameters.
*   `coarse: TransformerConfig` - Coarse transformer parameters.
*   `match_coarse: MatchCoarseConfig` - Coarse matching parameters.
*   `fine: FineConfig` - Fine transformer parameters.

### Implementations

#### `pub fn outdoor() -> Self`

Returns the default outdoor `LoFTR` preset used by this crate. This is also the `Default` configuration.

#### `pub fn indoor() -> Self`

Returns the legacy indoor `LoFTR` preset used by Kornia’s shared fixtures.

#### `pub fn indoor_new() -> Self`

Returns the indoor `LoFTR` preset with Kornia’s temperature fix enabled.
```

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

### Building the Backbone Network

Source: https://docs.rs/loftr/latest/src/loftr/backbone.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs the backbone network based on the provided configuration. Currently supports ResNetFpn with a resolution of (8, 2).

```rust
pub fn build_backbone(vs: &nn::Path<'_>, config: &LoftrConfig) -> Result<Backbone, LoftrError> {
    match config.backbone_type {
        crate::loftr_config::BackboneType::ResNetFpn => match config.resolution {
            (8, 2) => Ok(Backbone::ResNetFpn8_2(ResNetFpn8_2::new(
                &(vs / "backbone"),
                &config.resnetfpn,
            )?)),
            other => Err(LoftrError::InvalidConfig(format!(
                "Unsupported LoFTR backbone resolution {other:?}; only (8, 2) is ported so far"
            ))),
        },
    }
}
```

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

### ResNetFpn8_2 Initialization

Source: https://docs.rs/loftr/latest/src/loftr/backbone.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes a ResNetFpn8_2 backbone. This involves setting up convolutional layers, batch normalization, and residual layers according to the provided dimensions and configuration.

```rust
let bn1 = nn::batch_norm2d(&(vs / "bn1"), initial_dim, nn::BatchNormConfig::default());
        let (layer1, next_planes) = 
            ResNetLayer::new(&(vs / "layer1"), initial_dim, block_dims[0], 1);
        let (layer2, next_planes) = 
            ResNetLayer::new(&(vs / "layer2"), next_planes, block_dims[1], 2);
        let (layer3, _) = ResNetLayer::new(&(vs / "layer3"), next_planes, block_dims[2], 2);

        Ok(Self {
            conv1,
            bn1,
            layer1,
            layer2,
            layer3,
            layer3_outconv: conv1x1(&(vs / "layer3_outconv"), block_dims[2], block_dims[2], 1),
            layer2_outconv: conv1x1(&(vs / "layer2_outconv"), block_dims[1], block_dims[2], 1),
            layer2_outconv2: FpnHead::new(
                &(vs / "layer2_outconv2"),
                block_dims[2],
                block_dims[2],
                block_dims[1],
            ),
            layer1_outconv: conv1x1(&(vs / "layer1_outconv"), block_dims[0], block_dims[1], 1),
            layer1_outconv2: FpnHead::new(
                &(vs / "layer1_outconv2"),
                block_dims[1],
                block_dims[1],
                block_dims[0],
            ),
        })
```

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

### ResNetFpn8_2 Initialization

Source: https://docs.rs/loftr/latest/src/loftr/backbone.rs.html

Initializes the ResNetFpn8_2 backbone with specified dimensions and configuration. This involves setting up convolutional layers, batch normalization, and residual layers.

```rust
impl ResNetFpn8_2 {
    pub fn new(vs: &nn::Path<'_>, config: &ResNetFpnConfig) -> Result<Self, LoftrError> {
        let initial_dim = config.initial_dim;
        let block_dims = &config.block_dims;
        let conv1 = nn::conv2d(vs / "conv1", 1, initial_dim, 7, 1, 3, nn::ConvConfig::default());
        let bn1 = nn::batch_norm2d(&(vs / "bn1"), initial_dim, nn::BatchNormConfig::default());
        let (layer1, next_planes) = 
            ResNetLayer::new(&(vs / "layer1"), initial_dim, block_dims[0], 1);
        let (layer2, next_planes) = 
            ResNetLayer::new(&(vs / "layer2"), next_planes, block_dims[1], 2);
        let (layer3, _) = ResNetLayer::new(&(vs / "layer3"), next_planes, block_dims[2], 2);

        Ok(Self {
            conv1,
            bn1,
            layer1,
            layer2,
            layer3,
            layer3_outconv: conv1x1(&(vs / "layer3_outconv"), block_dims[2], block_dims[2], 1),
            layer2_outconv: conv1x1(&(vs / "layer2_outconv"), block_dims[1], block_dims[2], 1),
            layer2_outconv2: FpnHead::new(
                &(vs / "layer2_outconv2"),
                block_dims[2],
                block_dims[2],
                block_dims[1],
            ),
            layer1_outconv: conv1x1(&(vs / "layer1_outconv"), block_dims[0], block_dims[1], 1),
            layer1_outconv2: FpnHead::new(
                &(vs / "layer1_outconv2"),
                block_dims[1],
                block_dims[1],
                block_dims[0],
            ),
        })
    }
}
```

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

### CloneToUninit Implementation for T

Source: https://docs.rs/loftr/latest/loftr/enum.BackboneType.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Nightly-only experimental API for `clone_to_uninit` for types `T` that implement `Clone`.

```rust
impl<T> CloneToUninit for T
where T: Clone,
```

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

### Error::provide Method (Nightly Experimental)

Source: https://docs.rs/loftr/latest/loftr/enum.LoftrError.html

Nightly-only experimental API for providing type-based access to error context, intended for error reporting. Use with caution as it requires a nightly Rust toolchain.

```rust
fn provide<'a>(&'a self, request: &mut Request<'a>)
```

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

### ResNetFPN Backbone Configuration

Source: https://docs.rs/loftr/latest/src/loftr/loftr_config.rs.html

Configuration parameters for the ResNetFPN backbone, specifying initial and block dimensions.

```rust
/// Backbone parameters for the `ResNetFPN` encoder used by `LoFTR`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResNetFpnConfig {
    /// Channel count produced by the initial stem convolution.
    pub initial_dim: i64,
    /// Output channel counts for the three residual stages.
    pub block_dims: [i64; 3],
}
```

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

### PartialEq Implementation for FineConfig

Source: https://docs.rs/loftr/latest/loftr/struct.FineConfig.html?search=

Defines methods for testing equality between FineConfig values.

```rust
fn eq(&self, other: &FineConfig) -> bool
```

```rust
fn ne(&self, other: &Rhs) -> bool
```

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

### TryFrom and TryInto Implementations

Source: https://docs.rs/loftr/latest/loftr/struct.MatchCoarseConfig.html

Facilitates fallible conversions to and from `MatchCoarseConfig` types, handling potential errors during conversion.

```rust
type Error = Infallible
```

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

```rust
type Error = <U as TryFrom<T>>::Error
```

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

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

### LoFTRModel::new

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrModel.html

Constructs a LoFTR model instance on the specified device with the given configuration. This method allocates parameters but does not load weights.

```APIDOC
## LoftrModel::new

### Description
Builds a `LoFTR` model on the requested device.

### Method
`pub fn new(device: Device, config: LoftrConfig) -> Result<Self, LoftrError>`

### Parameters
#### Arguments
- `device` (Device) - Device where model parameters and inference tensors will live.
- `config` (LoftrConfig) - High-level `LoFTR` configuration preset or override set.

### Returns
A constructed model with allocated parameters but no loaded weights yet.

### Errors
Returns an error when the model configuration is invalid or one of the internal modules cannot be constructed.
```

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

### PartialEq Implementation for ResNetFpnConfig

Source: https://docs.rs/loftr/latest/loftr/struct.ResNetFpnConfig.html?search=

Provides methods for comparing ResNetFpnConfig instances for equality.

```rust
fn eq(&self, other: &ResNetFpnConfig) -> bool
```

```rust
fn ne(&self, other: &Rhs) -> bool
```

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

### LoFTRConfig Default Outdoor Preset

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrConfig.html

Returns the default outdoor LoFTR preset, which also serves as the default configuration.

```rust
pub fn outdoor() -> Self
```

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

### CoarseMatching::new

Source: https://docs.rs/loftr/latest/src/loftr/coarse_matching.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs a new CoarseMatching instance with the specified configuration. Currently, only the DualSoftmax match type is supported.

```APIDOC
## CoarseMatching::new

### Description

Initializes a `CoarseMatching` struct. The configuration must use `MatchType::DualSoftmax`.

### Signature

```rust
pub fn new(config: &MatchCoarseConfig) -> Self
```

### Parameters

- `config` (*&MatchCoarseConfig*): A reference to the coarse matching configuration.

### Returns

- `Self`: A new `CoarseMatching` instance.
```

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

### Clone Implementation for MatchCoarseConfig

Source: https://docs.rs/loftr/latest/loftr/struct.MatchCoarseConfig.html

Provides methods to duplicate MatchCoarseConfig values. The `clone` method creates a new instance with the same values, while `clone_from` performs copy-assignment.

```rust
fn clone(&self) -> MatchCoarseConfig
```

```rust
fn clone_from(&mut self, source: &Self)
```

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

### LoftrConfig Presets

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrConfig.html?search=

Provides functions to retrieve default and legacy configurations for the Loftr model.

```APIDOC
## LoftrConfig Presets

### `outdoor()`

Returns the default outdoor `LoFTR` preset used by this crate. This is also the `Default` configuration.

### `indoor()`

Returns the legacy indoor `LoFTR` preset used by Kornia’s shared fixtures.

### `indoor_new()`

Returns the indoor `LoFTR` preset with Kornia’s temperature fix enabled.
```

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

### Clone Implementation for FineConfig

Source: https://docs.rs/loftr/latest/loftr/struct.FineConfig.html?search=

Provides methods to create a duplicate of a FineConfig value or perform copy-assignment.

```rust
fn clone(&self) -> FineConfig
```

```rust
fn clone_from(&mut self, source: &Self)
```

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

### Clone Implementation for ResNetFpnConfig

Source: https://docs.rs/loftr/latest/loftr/struct.ResNetFpnConfig.html?search=

Provides methods for cloning ResNetFpnConfig instances.

```rust
fn clone(&self) -> ResNetFpnConfig
```

```rust
fn clone_from(&mut self, source: &Self)
```

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

### Clone Implementation for MatchCoarseConfig

Source: https://docs.rs/loftr/latest/loftr/struct.MatchCoarseConfig.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides the ability to create a deep copy of a MatchCoarseConfig instance. This is useful for duplicating configuration settings.

```rust
fn clone(&self) -> MatchCoarseConfig
```

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

### LoFTRModel::forward_debug

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrModel.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Runs `LoFTR` inference and returns intermediate debug statistics. Intended for parity checks and diagnostics rather than normal matching flows.

```APIDOC
## LoFTRModel::forward_debug

### Description
Runs `LoFTR` inference and returns intermediate debug statistics. This method is intended for parity checks and diagnostics rather than normal matching flows.

### Method
`pub fn forward_debug(&mut self, image0: &Tensor, image1: &Tensor) -> Result<LoftrDebugStages, LoftrError>`

### Arguments
* `image0` - Left image tensor.
* `image1` - Right image tensor.

### Returns
Aggregate statistics for the major intermediate tensors in the matching pipeline.

### Errors
Returns an error when the input shapes are unsupported or if any stage of the network execution fails.
```

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

### LoFTRModel::forward_debug

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrModel.html?search=

Runs LoFTR inference and returns intermediate debug statistics for diagnostics and parity checks.

```APIDOC
## LoftrModel::forward_debug

### Description
Runs `LoFTR` inference and returns intermediate debug statistics. This method is intended for parity checks and diagnostics rather than normal matching flows.

### Method
`pub fn forward_debug(&mut self, image0: &Tensor, image1: &Tensor) -> Result<LoftrDebugStages, LoftrError>`

### Arguments
* `image0` - Left image tensor.
* `image1` - Right image tensor.

### Returns
Aggregate statistics for the major intermediate tensors in the matching pipeline.

### Errors
Returns an error when the input shapes are unsupported or if any stage of the network execution fails.
```

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

### Build Debug Stages

Source: https://docs.rs/loftr/latest/src/loftr/loftr_model.rs.html?search=

Constructs a debug structure containing statistics for various intermediate tensors during the LoFTR process.

```rust
fn build_debug_stages(
        &self,
        image0: &Tensor,
        image1: &Tensor,
        backbone_features: &BackboneFeatures,
        coarse_features: &CoarseFeatures,
        coarse: &CoarseMatchingOutput,
    ) -> LoftrDebugStages {
        LoftrDebugStages {
            image0: tensor_debug_stats(image0),
            image1: tensor_debug_stats(image1),
            feat_c0_backbone: tensor_debug_stats(&backbone_features.coarse0),
            feat_c1_backbone: tensor_debug_stats(&backbone_features.coarse1),
            feat_f0_backbone: tensor_debug_stats(&backbone_features.fine0),
            feat_f1_backbone: tensor_debug_stats(&backbone_features.fine1),
            feat_c0_pos: tensor_debug_stats(&coarse_features.positional0),
            feat_c1_pos: tensor_debug_stats(&coarse_features.positional1),
            feat_c0_coarse: tensor_debug_stats(&coarse_features.transformed0),
            feat_c1_coarse: tensor_debug_stats(&coarse_features.transformed1),
            coarse: CoarseDebugStats {
                conf_matrix: tensor_debug_stats(&coarse.conf_matrix),
                threshold_count: coarse
                    .conf_matrix

```

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

### LoFTR Model Structure and Initialization

Source: https://docs.rs/loftr/latest/src/loftr/loftr_model.rs.html?search=u32+-%3E+bool

Defines the LoFTRModel struct and its constructor. This function initializes the model's components, including the backbone, positional encoding, and transformer layers, on a specified device with a given configuration. It returns a Result indicating success or a LoftrError.

```rust
use std::path::Path;

use serde::Serialize;

use tch::{
    Device, Kind, Tensor,
    nn::{self, VarStore},
};

use crate::{
    backbone::{Backbone, build_backbone},
    coarse_matching::{CoarseMatching, CoarseMatchingData, CoarseMatchingOutput},
    error::LoftrError,
    fine_matching::{FineMatching, FineMatchingData},
    fine_preprocess::{FinePreprocess, FinePreprocessData},
    loftr::{LoFTRMatches, normalize_loftr_image},
    loftr_config::LoftrConfig,
    position_encoding::PositionEncodingSine,
    transformer::LocalFeatureTransformer,
};

/// `LoFTR` model instance with owned weights and inference state.
///
/// Construct a model with [`Self::new`], load weights with
/// [`Self::load_weights`], and then run [`Self::forward`] or
/// [`Self::forward_debug`].
#[derive(Debug)]
pub struct LoFTRModel {
    config: LoftrConfig,
    var_store: VarStore,
    backbone: Backbone,
    pos_encoding: PositionEncodingSine,
    loftr_coarse: LocalFeatureTransformer,
    coarse_matching: CoarseMatching,
    fine_preprocess: FinePreprocess,
    loftr_fine: LocalFeatureTransformer,
}

/// Summary statistics for a tensor captured during debug inference.
///
/// This type is primarily intended for serialized validation output rather than
/// for general tensor manipulation.
#[derive(Debug, Serialize)]
pub struct TensorDebugStats {
    shape: Vec<i64>,
    mean: f64,
    std: f64,
    min: f64,
    max: f64,
    abs_mean: f64,
    l2_norm: f64,
    sample: Vec<f64>,
}

/// Summary statistics for coarse-stage matching outputs.
#[derive(Debug, Serialize)]
pub struct CoarseDebugStats {
    conf_matrix: TensorDebugStats,
    threshold_count: i64,
    mutual_count: i64,
    match_count: i64,
    confidence_mean: f64,
    confidence_max: f64,
}

/// Debug-stage summary returned by [`LoFTRModel::forward_debug`].
///
/// The contained values are aggregate statistics for intermediate tensors from
/// image normalization through coarse matching.
#[derive(Debug, Serialize)]
pub struct LoftrDebugStages {
    image0: TensorDebugStats,
    image1: TensorDebugStats,
    feat_c0_backbone: TensorDebugStats,
    feat_c1_backbone: TensorDebugStats,
    feat_f0_backbone: TensorDebugStats,
    feat_f1_backbone: TensorDebugStats,
    feat_c0_pos: TensorDebugStats,
    feat_c1_pos: TensorDebugStats,
    feat_c0_coarse: TensorDebugStats,
    feat_c1_coarse: TensorDebugStats,
    coarse: CoarseDebugStats,
}

impl LoFTRModel {
    /// Builds a `LoFTR` model on the requested device.
    ///
    /// # Arguments
    ///
    /// * `device` - Device where model parameters and inference tensors will live.
    /// * `config` - High-level `LoFTR` configuration preset or override set.
    ///
    /// # Returns
    ///
    /// A constructed model with allocated parameters but no loaded weights yet.
    ///
    /// # Errors
    ///
    /// Returns an error when the model configuration is invalid or one of the
    /// internal modules cannot be constructed.
    pub fn new(device: Device, config: LoftrConfig) -> Result<Self, LoftrError> {
        let var_store = nn::VarStore::new(device);
        let root = var_store.root();
        let backbone = build_backbone(&root, &config)?;
        let pos_encoding = PositionEncodingSine::new(
            config.coarse.d_model,
            (256, 256),
            config.coarse.temp_bug_fix,
            device,
        )?;
        let loftr_coarse =
            LocalFeatureTransformer::new(&(root.clone() / "loftr_coarse"), &config.coarse)?;
        let coarse_matching = CoarseMatching::new(&config.match_coarse);
        let fine_preprocess = FinePreprocess::new(&(root.clone() / "fine_preprocess"), &config)?;
        let fine_transformer_config = crate::loftr_config::TransformerConfig {
            d_model: config.fine.d_model,
            d_ffn: config.fine.d_ffn,
            nhead: config.fine.nhead,
            layers: config.fine.layers.clone(),
            attention: config.fine.attention,
            temp_bug_fix: false,
        };
        let loftr_fine =
            LocalFeatureTransformer::new(&(root / "loftr_fine"), &fine_transformer_config)?;
        Ok(Self {
            config,
            var_store,
            backbone,
            pos_encoding,
            loftr_coarse,
            coarse_matching,
            fine_preprocess,
            loftr_fine,
        })
    }

    /// Returns an immutable reference to the underlying `tch` variable store.
    ///
    /// This is useful when integrating with external `tch` helpers or inspecting
    /// loaded parameters.
    #[must_use]
    pub fn var_store(&self) -> &VarStore {
        &self.var_store
    }
}
```

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

### FinePreprocess Struct Definition and Constructor

Source: https://docs.rs/loftr/latest/src/loftr/fine_preprocess.rs.html?search=

Defines the `FinePreprocess` struct for transforming features and its constructor, which initializes linear layers for feature projection and merging if configured.

```rust
#[derive(Debug)]
pub struct FinePreprocess {
    cat_coarse_feat: bool,
    window_size: i64,
    d_model_f: i64,
    down_proj: Option<nn::Linear>,
    merge_feat: Option<nn::Linear>,
}

impl FinePreprocess {
    pub fn new(vs: &nn::Path<'_>, config: &LoftrConfig) -> Result<Self, LoftrError> {
        if config.fine_window_size <= 0 || config.fine_window_size % 2 == 0 {
            return Err(LoftrError::InvalidConfig(format!(
                "FinePreprocess requires a positive odd fine_window_size; got {}",
                config.fine_window_size
            )));
        }

        let d_model_c = config.coarse.d_model;
        let d_model_f = config.fine.d_model;
        let linear_config = nn::LinearConfig {
            ws_init: nn::init::DEFAULT_KAIMING_NORMAL,
            ..Default::default()
        };

        let (down_proj, merge_feat) = if config.fine_concat_coarse_feat {
            let down_proj = nn::linear(vs / "down_proj", d_model_c, d_model_f, linear_config);
            let merge_feat = nn::linear(vs / "merge_feat", 2 * d_model_f, d_model_f, linear_config);
            (Some(down_proj), Some(merge_feat))
        } else {
            (None, None)
        };

        Ok(Self {
            cat_coarse_feat: config.fine_concat_coarse_feat,
            window_size: config.fine_window_size,
            d_model_f,
            down_proj,
            merge_feat,
        })
    }

```

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

### LoFTREncoderLayer::new

Source: https://docs.rs/loftr/latest/src/loftr/transformer.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs a new LoFTREncoderLayer. It initializes projection layers, attention mechanisms, MLP, and layer normalization. Configuration validation is performed to ensure valid dimensions and head counts.

```APIDOC
## LoFTREncoderLayer::new

### Description
Constructs a new LoFTREncoderLayer. It initializes projection layers, attention mechanisms, MLP, and layer normalization. Configuration validation is performed to ensure valid dimensions and head counts.

### Parameters
- `vs` (nn::Path<'_>): The parameters path for initializing submodules.
- `d_model` (i64): The dimensionality of the model.
- `nhead` (i64): The number of attention heads.
- `attention` (AttentionType): The type of attention to use (Linear or Full).

### Returns
- `Result<Self, LoftrError>`: A `Result` containing the initialized `LoFTREncoderLayer` or a `LoftrError` if the configuration is invalid.
```

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

### LoFTRModel::forward

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrModel.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Runs `LoFTR` inference for one batch of image pairs. Inputs are normalized before inference. Returns matched keypoints, confidences, and batch indexes.

```APIDOC
## LoFTRModel::forward

### Description
Runs `LoFTR` inference for one batch of image pairs. Inputs may be grayscale or RGB tensors in any format accepted by `normalize_loftr_image`. Both images are normalized onto the model device before inference. Returns matched keypoints, confidences, and batch indexes for the input pairs.

### Method
`pub fn forward(&mut self, image0: &Tensor, image1: &Tensor) -> Result<LoftrMatches, LoftrError>`

### Arguments
* `image0` - Left image tensor.
* `image1` - Right image tensor.

### Returns
Matched keypoints, confidences, and batch indexes for the input pairs.

### Errors
Returns an error when the input shapes are unsupported or if any stage of the network execution fails.
```

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

### Load LoftrModel Weights

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrModel.html

Loads model weights from a `safetensors` or Torch-compatible checkpoint file. Ensure the checkpoint path is valid and matches the model's layout.

```rust
pub fn load_weights<P: AsRef<Path>>(
    &mut self,
    path: P,
) -> Result<(), LoftrError>
```

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

### Forward Pass with Debugging

Source: https://docs.rs/loftr/latest/src/loftr/loftr_model.rs.html?search=std%3A%3Avec

Executes the full LoFTR pipeline, including coarse and fine matching, and builds debug information for each stage. This is the main entry point for matching two images.

```rust
fn forward(
        &mut self,
        image0: &Tensor,
        image1: &Tensor,
        batch_size: i64,
        hw0_i: (i64, i64),
        hw1_i: (i64, i64),
    ) -> Result<ForwardWithDebug, LoftrError> {
        let backbone_features = self.backbone_features(image0, image1, batch_size, hw0_i, hw1_i)?;
        let mut coarse_features = self.coarse_features(&backbone_features, batch_size)?;

        let coarse = self.coarse_matching(&mut coarse_features, batch_size)?;

        let fine = self.fine_matching(&backbone_features, &coarse_features, &coarse, batch_size)?;

        Ok(ForwardWithDebug {
            matches: LoftrMatches {
                keypoints0: fine.mkpts0_f,
                keypoints1: fine.mkpts1_f,
                confidence: coarse.mconf.shallow_clone(),
                batch_indexes: coarse.m_bids.shallow_clone(),
            },
            debug: self.build_debug_stages(
                image0,
                image1,
                &backbone_features,
                &coarse_features,
                &coarse,
            ),
        })
    }
```

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

### LoFTRModel::load_weights Method

Source: https://docs.rs/loftr/latest/loftr/struct.LoftrModel.html?search=u32+-%3E+bool

Loads model weights from a safetensors or Torch-compatible checkpoint file. Ensure the checkpoint path is valid and matches the model's layout.

```rust
pub fn load_weights<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), LoftrError>
```

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

### LoFTR Encoder Layer Initialization

Source: https://docs.rs/loftr/latest/src/loftr/transformer.rs.html

Initializes a LoFTR encoder layer with specified dimensions, number of heads, and attention type. It includes input projections, attention mechanism, merge projection, MLP, and layer normalization. Configuration validation is performed.

```rust
pub fn new(
        vs: &nn::Path<'_>,
        d_model: i64,
        nhead: i64,
        attention: AttentionType,
    ) -> Result<Self, LoftrError> {
        if d_model <= 0 || nhead <= 0 || d_model % nhead != 0 {
            return Err(LoftrError::InvalidConfig(format!(
                "LoFTREncoderLayer requires positive d_model and nhead, with d_model divisible by nhead; got d_model={d_model}, nhead={nhead}"
            )));
        }

        let attention = match attention {
            AttentionType::Linear => AttentionKind::Linear(LinearAttention::default()),
            AttentionType::Full => AttentionKind::Full(FullAttention::default()),
        };
        let linear_config = nn::LinearConfig {
            bias: false,
            ..Default::default()
        };
        let mlp = nn::seq()
            .add(nn::linear(
                vs / "mlp" / "0",
                d_model * 2,
                d_model * 2,
                linear_config,
            ))
            .add_fn(Tensor::relu)
            .add(nn::linear(
                vs / "mlp" / "2",
                d_model * 2,
                d_model,
                linear_config,
            ));
        let layer_norm_config = nn::LayerNormConfig::default();

        Ok(Self {
            dim: d_model / nhead,
            nhead,
            q_proj: nn::linear(vs / "q_proj", d_model, d_model, linear_config),
            k_proj: nn::linear(vs / "k_proj", d_model, d_model, linear_config),
            v_proj: nn::linear(vs / "v_proj", d_model, d_model, linear_config),
            attention,
            merge: nn::linear(vs / "merge", d_model, d_model, linear_config),
            mlp,
            norm1: nn::layer_norm(vs / "norm1", vec![d_model], layer_norm_config),
            norm2: nn::layer_norm(vs / "norm2", vec![d_model], layer_norm_config),
        })
    }

```
Tokens:
Raw