How to Change the Resolution for RF-DETR Inference: 3 Methods Explained

To change the resolution for RF‑DETR inference, set the resolution parameter in ModelConfig before instantiating the model, ensuring the value is divisible by patch_size * num_windows as defined in src/rfdetr/variants.py.

RF‑DETR is a real-time transformer-based object detection model developed by Roboflow. Inference resolution directly impacts the trade-off between detection accuracy and processing speed, with higher resolutions improving small-object detection at the cost of latency. This guide explains how to configure input resolution using the library's configuration system and inference context.

Understanding the Resolution Architecture

ModelConfig and the Configuration Layer

In src/rfdetr/config.py, the ModelConfig dataclass defines the resolution: int field that drives both training and inference configurations. This parameter specifies the target square input size in pixels. When you instantiate RFDETR with a custom configuration, the constructor forwards this value to the underlying inference pipeline.

ModelContext and Inference State

The ModelContext class in src/rfdetr/inference.py (lines 39‑56) receives the resolution from ModelConfig and stores it as self.resolution. This value persists throughout the inference lifecycle and determines how input tensors are preprocessed before reaching the transformer backbone.

Post-Processing and Scaling

During inference, src/rfdetr/models/postprocess.py consumes the stored resolution to scale model outputs—bounding boxes, masks, and keypoints—back to the original image dimensions. Without the correct resolution context, predictions would be misaligned with the source imagery.

Resolution Constraints and Validation

According to src/rfdetr/variants.py, the resolution must be divisible by patch_size * num_windows. For example, the RFDETRSmall variant uses patch_size=16 and num_windows=2, requiring resolutions divisible by 32 (e.g., 640, 672, 704). Attempting to set an invalid resolution raises a validation error during model construction, preventing silent failures in the attention mechanism.

Three Methods to Change Inference Resolution

Method 1: Custom ModelConfig (Recommended)

Create a custom ModelConfig with your target resolution before building the detector. This ensures the ModelContext initializes with the correct dimensions from the first forward pass.

from rfdetr import RFDETR
from rfdetr.config import ModelConfig

# Configure for 800×800 pixel input

cfg = ModelConfig(size="rfdetr-small", resolution=800)
detector = RFDETR(cfg)

# Obtain the inference context with the new resolution baked in

ctx = detector.get_model()
print(f"Resolution set to: {ctx.resolution}")  # Output: 800

Method 2: Override Pre-trained Checkpoints

Load a standard checkpoint via from_pretrained and modify the resolution before creating the inference context. This approach preserves learned weights while adapting the model to new input dimensions.

from rfdetr import RFDETR

# Load default checkpoint (typically 640×640)

detector = RFDETR.from_pretrained("rfdetr-small")

# Override resolution (must satisfy divisor rule)

detector.model_config.resolution = 800

# Re-create ModelContext to apply the change

ctx = detector.get_model()

Method 3: Modify Existing ModelContext (Advanced)

For specialized debugging or research scenarios, you can mutate the resolution on an existing context. This requires rebuilding internal components to maintain consistency with positional embeddings sized at construction time.

# Assuming ctx is an existing ModelContext instance

new_ctx = ctx._build_model_context(
    model_config=ctx.args,
    trust_checkpoint=False
)
new_ctx.resolution = 800  # Direct mutation (not recommended for production)

Verifying the Configuration

Always validate that your resolution meets the architectural constraints before running inference. The system checks divisibility early and raises descriptive errors if constraints are violated.

from rfdetr.variants import RFDETRSmall

variant = RFDETRSmall()
divisor = variant.model_config.patch_size * variant.model_config.num_windows
print(f"Required divisor: {divisor}")  # 32 for small variant

# Verify your chosen resolution

assert 800 % divisor == 0, "Resolution violates patch size constraints"

Summary

• Configuration origin: Resolution is defined in ModelConfig (src/rfdetr/config.py) and stored in ModelContext (src/rfdetr/inference.py).
• Divisibility rule: Values must be divisible by patch_size * num_windows as specified in src/rfdetr/variants.py.
• Best practice: Set resolution via ModelConfig before instantiating RFDETR to avoid rebuilding contexts.
• Validation: Access ctx.resolution after calling get_model() to confirm the active configuration.

Frequently Asked Questions

What is the default inference resolution for RF‑DETR?

Pre-trained checkpoints typically default to 640×640 pixels, though this varies by model variant. You can verify the current setting by inspecting detector.model_config.resolution before building the inference context.

Why does RF‑DETR require specific resolution divisibility?

The transformer architecture processes images as patches. According to src/rfdetr/variants.py, the resolution must align with the window-based attention mechanism, specifically divisible by patch_size * num_windows. This ensures the spatial dimensions evenly divide into the feature map grid without fractional patches.

Can I use rectangular resolutions with RF‑DETR?

No. The ModelConfig system enforces square inputs through a single resolution: int parameter. Both height and width are set to this value during preprocessing. For non-square source images, the library pads and letterboxes the input while maintaining the aspect ratio, then scales predictions back using the stored resolution.

What happens if I set a resolution that violates the divisor rule?

The model raises a validation error during get_model() or _build_model_context(), typically referencing the specific patch_size and num_windows requirements for your chosen variant. The check occurs early in the initialization process to prevent runtime failures during the forward pass.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}