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

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 (lines 19-26), the code calculates the target resolution using the formula:

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 (lines 62-66), the generate_stl function creates a vertex array where each pixel becomes one vertex in the 3D mesh:

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 (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 (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 file (lines 31-54) exposes a /convert endpoint that accepts detail_level as a form parameter. You can test different values programmatically:

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 accepts detail_level via argument parsing (lines 63-124 in the CLI block):

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

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

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

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

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