Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ragavsachdeva/CYWS-3D/llms.txt

Use this file to discover all available pages before exploring further.

All CYWS-3D training and inference runs are driven by a single YAML configuration file. The file is passed to inference.py via --config_file and loaded at startup using get_easy_dict_from_yaml_file(), which returns a dot-accessible namespace. Every field that controls model architecture, optimiser behaviour, and data loading lives in this one file — there are no hard-coded defaults scattered across the codebase.

​
Full config.yml

vit_feature_layers: [2, 11]

encoder:
  stride: 4
  patch: 8
  keep_cls_in_seq2spatial: False
  output_dim: 768

decoder:
  downsampling_blocks: [[768, 512], [512, 512], [512, 512], [512, 512]]
  encoder_channels: [0, 768, 512, 512, 512, 512]
  decoder_channels: [256, 256, 128, 128, 64]

batch_size: 8
num_dataloader_workers: 8
lr: 0.0001
weight_decay: 0.0005
imagenet_normalisation: True

​
Top-level fields

​
vit_feature_layers
list[int]
required
Indices of the DINOv2 ViT transformer blocks whose output activations are hooked for feature extraction. The default [2, 11] captures an early low-level layer and the final semantic layer of a 12-block ViT-S/8 backbone. The number of entries here implicitly determines how many skip connections the encoder produces.
​
batch_size
int
default:"8"
Number of image pairs per training step. Each sample in the batch may use a different registration strategy ("3d", "2d", or "identity"), so the effective GPU memory footprint varies with the mix of input geometry.
​
num_dataloader_workers
int
default:"8"
Number of parallel worker processes spawned by torch.utils.data.DataLoader for data loading and augmentation. Reduce this value if you encounter shared-memory errors in constrained environments.
​
lr
float
default:"0.0001"
Base learning rate passed to the AdamW optimiser. The same rate is applied to both the encoder (DINOv2 features) and the decoder unless overridden by a per-parameter-group schedule.
​
weight_decay
float
default:"0.0005"
L2 weight-decay coefficient for the AdamW optimiser. Applied uniformly to all parameters.
​
imagenet_normalisation
bool
default:"True"
When True, input images are normalised using the standard ImageNet mean [0.485, 0.456, 0.406] and standard deviation [0.229, 0.224, 0.225] before being passed to the DINOv2 encoder. This matches the pre-training distribution of the backbone and should remain True unless you are fine-tuning from scratch on a domain with a very different pixel distribution.

​
encoder

Settings for the DINOv2 ViT encoder that produces the dense feature maps fed to the registration module and decoder.
​
encoder.stride
int
default:"4"
Pixel stride used when converting the ViT sequence tokens back to a spatial feature map. A stride of 4 with a patch size of 8 produces a feature map at 1/4 the input resolution. This value must evenly divide encoder.patch.
​
encoder.patch
int
default:"8"
ViT patch size in pixels. Matches the DINOv2-S/8 backbone patch size. Each patch is flattened into a single sequence token by the transformer.
​
encoder.keep_cls_in_seq2spatial
bool
default:"False"
Controls whether the CLS token is concatenated into the spatial feature map during the sequence-to-spatial conversion step. When False (default) the CLS token is discarded, keeping the feature map dimensions consistent with the decoder’s expected input size.
​
encoder.output_dim
int
default:"768"
Channel dimension of the features produced by the DINOv2 ViT-S/8 backbone. This value propagates directly into the first entry of decoder.encoder_channels and the first downsampling_blocks input channel count.
Do not change encoder.stride or encoder.patch unless you are retraining from scratch. The released pre-trained checkpoint was trained with stride=4 and patch=8. Changing either value will invalidate the learned weights and produce incorrect outputs.

​
decoder

Settings for the UNet-style decoder that takes registered feature maps and predicts per-pixel change masks together with bounding box proposals.
​
decoder.downsampling_blocks
list[list[int]]
default:"[[768,512],[512,512],[512,512],[512,512]]"
Defines the channel progression through the series of DownSamplingBlock modules that compress the encoder output before the UNet skip connections are reintroduced. Each inner list [in_ch, out_ch] specifies one block. The four blocks here progressively reduce 768 → 512 and then maintain 512 channels through three further blocks.
​
decoder.encoder_channels
list[int]
default:"[0, 768, 512, 512, 512, 512]"
The encoder_channels argument passed to UnetDecoder. Each entry specifies the number of channels contributed by the corresponding encoder skip connection at that decoder stage. The leading 0 indicates that the deepest stage receives no skip connection from the encoder.
​
decoder.decoder_channels
list[int]
default:"[256, 256, 128, 128, 64]"
Output channel sizes for each successive UnetDecoder upsampling stage. The five values correspond to the five resolution levels at which the decoder produces feature maps, culminating in a 64-channel map at the original input resolution before the final prediction head.
The lengths of decoder.downsampling_blocks, decoder.encoder_channels, and decoder.decoder_channels are coupled. If you add or remove a stage in one list you must make corresponding changes to all three — and to the vit_feature_layers list if the number of skip connections changes.

​
Usage

Pass the config file path to inference.py at the command line: 
python inference.py \
  --config_file config.yml \
  --checkpoint path/to/checkpoint.pth \
  --image1 view1.jpg \
  --image2 view2.jpg
Inside the codebase, the file is loaded as: 
from utils import get_easy_dict_from_yaml_file

args = get_easy_dict_from_yaml_file("config.yml")

# Dot-access for any field, e.g.:
print(args.encoder.stride)        # 4
print(args.vit_feature_layers)    # [2, 11]
print(args.decoder.decoder_channels)  # [256, 256, 128, 128, 64]
To experiment with different training hyperparameters without modifying the released config.yml, copy the file and pass the copy via --config_file. All architecture fields (encoder.*, decoder.*, vit_feature_layers) should remain unchanged to preserve compatibility with the pre-trained checkpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us