# How the detail_level Parameter Affects STL File Size and Processing Time in MCP 3D Relief

> Learn how MCP 3D Relief detail_level impacts STL file size and processing time. Explore the quadratic relationship between detail, resolution, and vertex count for better optimization.

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

---

**Increasing the `detail_level` parameter in the MCP 3D Relief generator quadratically expands the intermediate depth map resolution, directly increasing vertex count, STL file size, and processing time.**

The `detail_level` parameter in the `bigchx/mcp_3d_relief` repository controls the trade-off between 3D model fidelity and computational resources. This setting determines how finely the source image is sampled before conversion to an STL mesh, directly impacting both the output file size and the time required for generation.

## Understanding the detail_level Parameter

The `detail_level` acts as a scalar multiplier for the base resolution of the depth map generation. In [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py) (lines 19-26), the code calculates the target resolution using the formula:

```python
base_size = 320 * detail_level

```

This `base_size` value determines the dimensions of the intermediate image that gets processed into a 3D mesh. The source image is resized so that its larger dimension matches this calculated base size, with the aspect ratio preserved through a computed scaling ratio applied to both width and height.

## Impact on Depth Map Resolution and Vertex Count

### How Resolution Scales with detail_level

The relationship between `detail_level` and pixel count is quadratic. When you increase the `detail_level`, the number of pixels in the depth map approximates to `(320 × detail_level)²`. For example:

- At `detail_level=0.5`: approximately 25,600 pixels
- At `detail_level=1.0`: approximately 102,400 pixels  
- At `detail_level=2.0`: approximately 409,600 pixels

### From Pixels to Vertices

In [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py) (lines 62-66), the `generate_stl` function creates a vertex array where each pixel becomes one vertex in the 3D mesh:

```python
vertices[y, x] = [x * pixel_size, y * pixel_size, depth]

```

This one-to-one mapping means the vertex count scales identically to the pixel count. More vertices require more memory allocation and increase the complexity of subsequent mesh operations.

## Effects on STL File Size

The STL file size grows quadratically with `detail_level` due to the facet generation process. In [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py) (lines 67-145), the `write_facet` function generates approximately four facets per pixel:

- Two facets for the top surface triangles
- Additional facets for the base and side walls

The total facet count approximates to `4 × pixel_count`, which translates to `4 × (320 × detail_level)²`. Since STL files store each facet as a 50-byte record (plus header), file size increases by roughly a factor of four when doubling the `detail_level`.

## Processing Time Implications

### Image Resizing and Blurring

The depth map creation in [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py) (lines 25-33 within `generate_depth_map`) involves OpenCV resize operations and Gaussian blurring. These are **O(width × height)** operations, meaning processing time increases quadratically with `detail_level`. Higher resolution images require more CPU cycles for convolution operations and consume additional memory bandwidth.

### Mesh Generation Overhead

The vertex array creation (lines 62-66) and facet generation loop (lines 67-145) iterate over every pixel in the depth map. As pixel count grows with the square of `detail_level`, the nested loop operations and file I/O for STL writing consume progressively more time. The facet writing process is particularly I/O-intensive, creating a bottleneck when generating millions of triangles.

## Practical Code Examples

### Using the FastAPI Endpoint

The [`server.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/server.py) file (lines 31-54) exposes a `/convert` endpoint that accepts `detail_level` as a form parameter. You can test different values programmatically:

```python
import requests
import time

def benchmark_conversion(image_path, detail_level):
    start = time.time()
    response = requests.post(
        "http://localhost:8000/convert",
        data={
            "image_path": image_path,
            "detail_level": detail_level,
            "model_width": 50,
            "model_thickness": 5,
            "base_thickness": 2,
        },
    )
    duration = time.time() - start
    return response.json(), duration

# Compare performance

low_detail_result, low_time = benchmark_conversion("input.jpg", 0.5)
high_detail_result, high_time = benchmark_conversion("input.jpg", 2.0)

print(f"Low detail (0.5): {low_time:.2f}s, file: {low_detail_result['output_path']}")
print(f"High detail (2.0): {high_time:.2f}s, file: {high_detail_result['output_path']}")

```

### Command Line Interface

For direct script execution, [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py) accepts `detail_level` via argument parsing (lines 63-124 in the CLI block):

```bash

# Fast, low-detail output (~25KB STL)

python relief.py input.png --detail_level 0.5 --output_dir ./output

# Standard detail (~100KB STL)  

python relief.py input.png --detail_level 1.0 --output_dir ./output

# High detail, large file (~400KB+ STL)

python relief.py input.png --detail_level 2.0 --output_dir ./output

```

### Measuring File Size and Runtime

On Linux systems, you can quantify the exact relationship between `detail_level` and resource usage:

```bash
#!/bin/bash

# benchmark.sh - Compare STL generation performance

INPUT_IMAGE="test_photo.jpg"
DETAIL_LEVELS=(0.5 1.0 1.5 2.0)

for detail in "${DETAIL_LEVELS[@]}"; do
    echo "Testing detail_level=$detail"
    
    # Time the execution

    time python relief.py "$INPUT_IMAGE" --detail_level "$detail"
    
    # Check output file size

    ls -lh output/*.stl | awk '{print "File size: " $5}'
    
    echo "----------------------------------------"
done

```

## Summary

- The `detail_level` parameter in `bigchx/mcp_3d_relief` scales the intermediate depth map resolution by the formula `base_size = 320 * detail_level`, creating a quadratic relationship between the parameter value and pixel count.

- **STL file size** increases quadratically with `detail_level` because each pixel generates approximately four facets in the mesh, and STL format stores each facet as a fixed-size binary record.

- **Processing time** grows quadratically due to O(n²) image resizing operations, Gaussian blurring, and the iterative vertex/facet generation loops in [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py).

- Lower values (0.5-0.8) produce fast, compact STLs suitable for draft prints, while values above 1.5 create high-fidelity models requiring significantly more memory and storage.

## Frequently Asked Questions

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

The default `detail_level` is typically set to `1.0` when not specified via command line or API call. This value produces a base resolution of 320 pixels on the longest edge of the input image, balancing quality and performance for general use cases. You can override this default by explicitly passing the parameter to the `relief()` function or via the FastAPI endpoint in [`server.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/server.py).

### How do I calculate the expected STL file size before generation?

You can estimate the final STL size using the formula derived from the source code implementation: approximately `4 × (320 × detail_level)² × 50 bytes` for the facet data plus a small header. For example, at `detail_level=1.0`, expect roughly 20-25MB of raw facet data. In practice, the actual file size may vary slightly depending on the base thickness and side wall geometry, but the quadratic scaling relationship remains consistent.

### Can I set detail_level above 2.0 for ultra-high resolution?

While the code does not enforce an upper bound on `detail_level` in [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py), values above `2.0` are generally not recommended for production use. At `detail_level=3.0`, the depth map approaches 960×960 pixels or larger depending on aspect ratio, generating millions of vertices and facets. This can exhaust available system memory during the `vertices` array allocation (line 62-66) and produce STL files exceeding 100MB, causing significant I/O bottlenecks during the facet writing phase.

### Does detail_level affect the physical dimensions of the 3D model?

No, the `detail_level` parameter only affects the **resolution** of the mesh, not the physical dimensions. The actual width, thickness, and height of the printed model are controlled by separate parameters: `model_width`, `model_thickness`, and `base_thickness`. In [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py), the `pixel_size` variable (calculated from `model_width` divided by image width) scales the vertex coordinates to real-world units, ensuring that a higher `detail_level` produces a more detailed surface texture within the same physical footprint rather than enlarging the model itself.