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

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.

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 at lines 26‑27, the code establishes a baseline pixel dimension:

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 compute the scaling ratio:

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, it creates a quad (two triangles) for each depth-map cell:

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)

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)

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)

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 – Contains the core logic for base_size calculation, aspect-ratio scaling, and the generate_stl function that converts depth maps to vertices.
• server.py – API wrapper that accepts the detail_level parameter and forwards it to the relief processing pipeline.
• 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 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.

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

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