Configuration

Customize Image Matching WebUI behavior with YAML configuration

Configuration

Image Matching WebUI uses YAML configuration files to customize behavior and default parameters.

Configuration File Location

Configuration files are loaded in priority order (first found):

1. Custom path: -c /path/to/config.yaml
2. Working directory: ./app.yaml
3. Config subdirectory: ./config/app.yaml
4. Package default: imcui/config/app.yaml

Essential Settings

Device Selection

Device is automatically detected at runtime based on your hardware:

• CUDA: Auto-selected if CUDA GPU is available
• CPU: Default fallback when CUDA is unavailable
• MPS: Auto-selected on macOS with Apple Silicon

Force CPU Mode

Set environment variable before running:

CUDA_VISIBLE_DEVICES="" imcui

Select Specific GPU

Use environment variable:

export CUDA_VISIBLE_DEVICES=0
imcui

Default Matcher

There is no default_matcher configuration. Matchers are loaded dynamically from the vismatch package and selected through the UI dropdown during matching.

Available matchers: See algorithm reference

Matching Parameters

Thresholds

defaults:
  setting_threshold: 0.1      # Detection sensitivity
  keypoint_threshold: 0.05    # Keypoint detection
  match_threshold: 0.2        # Match confidence
  max_keypoints: 2000         # Maximum feature points

RANSAC Filtering

defaults:
  enable_ransac: true
  ransac_method: CV2_USAC_MAGSAC
  ransac_reproj_threshold: 8.0
  ransac_confidence: 0.9999
  ransac_max_iter: 10000
  ransac_num_samples: 4

Supported RANSAC methods:

• RANSAC - Basic random sampling
• CV2_USAC_MAGSAC - Magnitude-consistent RANSAC (recommended)
• LMEDS - Least Median of Squares

Geometry Estimation

defaults:
  setting_geometry: Homography    # Options: Homography, Fundamental, Essential

Essential Matrix Settings

Note: Essential matrix parameters are configured through the UI when selecting Essential matrix geometry type. Requires camera intrinsics (focal length and principal point).

Example Configurations

Minimal Setup

defaults:
  setting_threshold: 0.1
  max_keypoints: 2000
  enable_ransac: true

Production Configuration

defaults:
  setting_threshold: 0.1
  keypoint_threshold: 0.05
  match_threshold: 0.2
  max_keypoints: 5000
  enable_ransac: true
  ransac_method: CV2_USAC_MAGSAC
  ransac_reproj_threshold: 8.0
  ransac_confidence: 0.9999
  ransac_max_iter: 10000
  setting_geometry: Homography

Development Configuration

defaults:
  setting_threshold: 0.2
  max_keypoints: 500
  match_threshold: 0.3
  enable_ransac: false

Developer note: Set CUDA_VISIBLE_DEVICES="" before running to force CPU mode.

Advanced Configuration

Dataset Path

example_data_root: /path/to/custom/datasets

Tip: Dataset paths can also be set via environment variable (IMCUI_DATA_DIR) or CLI flag (-d).

Configuration Profiles

Create multiple configurations for different use cases:

# Fast matching for previewing
imcui -c config_fast.yaml

# High-quality matching for production
imcui -c config_high_quality.yaml

# CPU-only matching for testing
CUDA_VISIBLE_DEVICES="" imcui -c config_cpu.yaml -d /test/data

Using Matchers

Matchers are selected through the web interface dropdown. The available matchers are automatically loaded from the vismatch package:

• Sparse matchers: SuperPoint + LightGlue, ORB, SIFT, etc.
• Dense matchers: LoFTR, RoMa, etc.

Need help selecting a matcher? Check our algorithm guide for performance characteristics and recommendations.