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

> Learn how to change the resolution for RF-DETR inference with 3 effective methods. Optimize your object detection models by adjusting the resolution parameter in ModelConfig for better performance.

- Repository: [Roboflow/rf-detr](https://github.com/roboflow/rf-detr)
- Tags: how-to-guide
- Published: 2026-09-08

---

**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`](https://github.com/roboflow/rf-detr/blob/main/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`](https://github.com/roboflow/rf-detr/blob/main/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`](https://github.com/roboflow/rf-detr/blob/main/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`](https://github.com/roboflow/rf-detr/blob/main/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`](https://github.com/roboflow/rf-detr/blob/main/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.

```python
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.

```python
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.

```python

# 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.

```python
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`](https://github.com/roboflow/rf-detr/blob/main/src/rfdetr/config.py)) and stored in `ModelContext` ([`src/rfdetr/inference.py`](https://github.com/roboflow/rf-detr/blob/main/src/rfdetr/inference.py)).
- **Divisibility rule**: Values must be divisible by `patch_size * num_windows` as specified in [`src/rfdetr/variants.py`](https://github.com/roboflow/rf-detr/blob/main/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`](https://github.com/roboflow/rf-detr/blob/main/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.