# How Mesh Resolution Is Calculated for Different detail_level Values in MCP 3D Relief

> Learn how mesh resolution is calculated in MCP 3D Relief. Discover the formula `base_size = 320 * detail_level` that scales depth map pixels to STL vertex count for desired detail levels.

- Repository: [bigchx/mcp_3d_relief](https://github.com/bigchx/mcp_3d_relief)
- Tags: internals
- Published: 2026-02-26

---

**Mesh resolution scales linearly with the `detail_level` parameter via the formula `base_size = 320 * detail_level`, which determines the depth map pixel dimensions that directly translate to the final STL vertex count.**

The `bigchx/mcp_3d_relief` repository generates 3D printable relief models by converting images into depth maps and extruding them into meshes. Understanding how the `detail_level` argument controls output fidelity requires examining the transformation from input pixels to mesh vertices in [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py).

## The Math Behind detail_level and Mesh Resolution

### Base Size Calculation

The resolution pipeline begins with a proportional scaling factor derived from `detail_level`. In [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py) at lines 26‑27, the code establishes a baseline pixel dimension:

```python
base_size = 320 * detail_level

```

The constant **320 pixels** represents the default resolution when `detail_level = 1.0`. This value serves as the maximum dimension (width or height) for the intermediate depth map that feeds the mesh generator.

### Aspect Ratio Preservation

To prevent distortion, the algorithm preserves the original image’s aspect ratio while fitting it within the `base_size` square boundary. Lines 28‑30 in [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py) compute the scaling ratio:

```python
ratio = min(base_size / width, base_size / height)
new_width, new_height = int(width * ratio), int(height * ratio)

```

This ensures the longer side of the resized image equals `base_size`, while the shorter side scales proportionally. The resulting `new_width` and `new_height` define the grid dimensions for the depth map array.

### From Pixels to Vertices

The `generate_stl` function (starting at line 55) iterates over every pixel in the depth map to construct the mesh. As implemented in [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py), it creates a quad (two triangles) for each depth-map cell:

```python
height, width = depth_map.shape          # generate_stl, line 55

pixel_size = model_width / width

```

Consequently, **the total vertex count equals `new_width * new_height`** (plus additional vertices for the base plate and side walls). Doubling `detail_level` quadruples the pixel count, directly increasing the STL file size by approximately 4×.

## Practical Impact on File Size and Quality

The relationship between `detail_level` and output characteristics follows a predictable quadratic growth pattern:

| detail_level | base_size (px) | Approximate Pixel Count (square image) | Typical STL Size |
|--------------|----------------|----------------------------------------|------------------|
| 0.5          | 160            | 25,600                                 | ~25 MB           |
| 1.0          | 320            | 102,400                                | ~100 MB          |
| 2.0          | 640            | 409,600                                | ~400 MB          |
| 3.0          | 960            | 921,600                                | ~900 MB          |

As noted in the repository’s documentation, “At `detail_level = 1.0`, the image is processed at **320 px** resolution, producing an STL typically under **100 MB**. Doubling the detail level can increase the STL size by **4×** or more.”

## Implementation Examples

### Default Resolution (detail_level = 1.0)

```python
import asyncio
import relief

result = asyncio.run(
    relief.relief(
        input_image_path="uploads/demo.png"
        # detail_level defaults to 1.0

    )
)
print(result["stl_path"])

```

This produces a depth map of roughly **320 px** on the longest side, generating approximately 100,000 vertices and a ~100 MB STL file.

### High-Detail Mode (detail_level = 2.0)

```python
import asyncio
import relief

result = asyncio.run(
    relief.relief(
        input_image_path="uploads/demo.png",
        detail_level=2.0      # 640 px max side

    )
)
print(result["stl_path"])

```

Setting `detail_level` to 2.0 yields a **640 px** depth map, creating ~400,000 pixels and a corresponding STL of approximately 400 MB.

### Fast Preview Mode (detail_level = 0.5)

```python
import asyncio
import relief

result = asyncio.run(
    relief.relief(
        input_image_path="uploads/demo.png",
        detail_level=0.5      # 160 px max side

    )
)
print(result["stl_path"])

```

This reduces the depth map to **160 px**, resulting in only ~25,000 pixels and a lightweight STL under 30 MB, suitable for rapid iteration at the cost of surface detail.

## Key Source Files

The mesh resolution calculation spans three critical files in the repository:

- **[`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py)** – Contains the core logic for `base_size` calculation, aspect-ratio scaling, and the `generate_stl` function that converts depth maps to vertices.
- **[`server.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/server.py)** – API wrapper that accepts the `detail_level` parameter and forwards it to the relief processing pipeline.
- **[`README.md`](https://github.com/bigchx/mcp_3d_relief/blob/main/README.md)** – Documents the expected file size implications and recommended `detail_level` values for different use cases.

## Summary

- **Mesh resolution** is determined by the formula `base_size = 320 * detail_level`, where 320 px is the baseline for `detail_level = 1.0`.
- **Vertex count grows quadratically** with `detail_level` because the algorithm creates one quad per depth-map pixel.
- **STL file size scales proportionally** to vertex count, typically ranging from ~25 MB at `detail_level = 0.5` to ~900 MB at `detail_level = 3.0`.
- The aspect-ratio preservation logic in [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py) ensures the mesh maintains the original image proportions while respecting the `base_size` boundary.

## Frequently Asked Questions

### What is the default detail_level in MCP 3D Relief?

The default value is **1.0**, which processes images at **320 pixels** on the longest side. This setting balances detail and file size, typically generating STL files under 100 MB according to the source code in [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py).

### How does detail_level affect STL file size?

STL file size increases roughly with the **square** of `detail_level`. Because the vertex count equals the depth map width multiplied by height, doubling `detail_level` from 1.0 to 2.0 quadruples the pixel count and produces an STL approximately 4× larger (from ~100 MB to ~400 MB).

### Can I use decimal values for detail_level?

Yes. The `detail_level` parameter accepts floating-point values such as 0.5, 1.5, or 2.0. The calculation `base_size = 320 * detail_level` applies linearly, so a value of 0.5 yields 160 px resolution while 1.5 yields 480 px.

### Why does the mesh resolution depend on the depth map size?

In `generate_stl` (line 55 of [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py)), the algorithm iterates over every pixel in the `depth_map` NumPy array to generate surface geometry. Each pixel becomes a mesh cell (two triangles), meaning the **depth map dimensions directly dictate the vertex density** and geometric fidelity of the final 3D model.