Dependencies Required for the Depth Estimation Pipeline in mcp_3d_relief

The depth estimation pipeline in bigchx/mcp_3d_relief requires NumPy, Pillow, and OpenCV for core image processing, plus aiohttp and asyncio for asynchronous operations, as declared in requirements.txt.

The bigchx/mcp_3d_relief repository implements a complete 3D relief generation system that transforms 2D images into depth maps and printable STL models. Understanding the dependencies required for the depth estimation pipeline is essential for local deployment, debugging, and customizing the core algorithms. The project separates its computer vision logic from web service concerns, allowing for minimal installations when API functionality is not needed.

Core Dependencies for Depth Estimation

The depth estimation algorithm is implemented in relief.py and relies on three fundamental libraries for image manipulation and numerical computation. These packages handle everything from initial image loading to final depth array calculations.

NumPy for Array Operations

NumPy (numpy>=1.20.0) provides the foundational array data structures used throughout the pipeline. The generate_depth_map function converts Pillow images into NumPy arrays and performs vectorized mathematical operations to calculate depth values from pixel intensity. All intermediate depth calculations and normal vector computations rely on NumPy's optimized C-backed arrays.

Pillow for Image I/O

Pillow (pillow>=8.0.0) supplies the Image class used to open, resize, and convert source images to grayscale before depth processing begins. The pipeline uses Pillow's format detection and decoding capabilities to handle various input types (JPEG, PNG, etc.), ensuring consistent 8-bit grayscale arrays for the depth estimation algorithm.

OpenCV for Computer Vision Tasks

OpenCV (opencv-python>=4.5.0) provides the cv2 module for resizing, Gaussian blur operations, and alternative image I/O methods. While Pillow handles initial loading, OpenCV performs the heavy-duty computer vision operations on the NumPy array representations, particularly the smoothing and scaling operations applied to the generated depth map.

Async and Network Dependencies

The pipeline supports asynchronous processing of remote images through additional libraries that enable non-blocking I/O operations.

aiohttp for Remote Image Downloading

aiohttp (aiohttp>=3.8.2) enables the relief function to accept remote URLs as input_image_path arguments. Before depth processing begins, the library asynchronously downloads image data without blocking the event loop, allowing the pipeline to handle cloud-hosted images efficiently while maintaining responsive performance.

asyncio for Workflow Management

asyncio (asyncio>=3.4.3) powers the async workflow that wraps the depth-map generation. While the core generate_depth_map function performs CPU-bound work synchronously, the high-level relief orchestrator uses asyncio to manage concurrent I/O operations and coordinate the pipeline stages.

Web Service Dependencies

Several packages listed in requirements.txt support the API layer in server.py rather than the core depth algorithm.

FastAPI (fastapi>=0.68.0), Uvicorn (uvicorn>=0.15.0), and python-multipart (python-multipart>=0.0.5) are required only when running the HTTP API server. These handle request parsing, multipart file uploads, and ASGI server functionality in server.py.

FastMCP (fastmcp>=2.2.2) integrates the FastAPI application with the MCP (Model Context Protocol) framework. While critical for the server deployment, none of these web dependencies are imported or used within relief.py itself.

Installation via requirements.txt

All dependency constraints are declared in the requirements.txt file located at the repository root. Install the complete environment using:

pip install -r requirements.txt

For minimal depth estimation functionality without the web API, install only the core dependencies:

pip install "numpy>=1.20.0" "pillow>=8.0.0" "opencv-python>=4.5.0"

Implementation in relief.py

The generate_depth_map function in relief.py (lines 25-49) directly imports and uses the core libraries. The function accepts a Pillow Image object, converts it to a NumPy array for mathematical processing, and utilizes OpenCV for final image transformations before returning a depth array.

This tight integration means that NumPy, Pillow, and OpenCV must always be present to execute the depth estimation algorithm, while the async and web libraries only become necessary when using the high-level relief function or the FastAPI server.

Practical Code Examples

Generate a depth map from a local image using only the core dependencies:

import asyncio
from PIL import Image
from relief import generate_depth_map

async def demo():
    img = Image.open("path/to/photo.jpg")
    depth = await generate_depth_map(img, detail_level=1.2, invert_depth=False)
    
    # Save using Pillow

    from PIL import Image as PILImage
    PILImage.fromarray(depth).save("depth_map.png")

asyncio.run(demo())

Execute the full pipeline including remote image downloading and STL generation:

import asyncio
from relief import relief

async def run():
    result = await relief(
        input_image_path="https://example.com/image.jpg",
        detail_level=1.0,
        model_width=50,
        model_thickness=5,
        base_thickness=2,
        output_dir="./output",
        skip_depth=False,
        invert_depth=False,
    )
    print(result)  # Contains paths to depth map and STL files

asyncio.run(run())

Summary

• The core depth estimation pipeline requires NumPy (>=1.20.0), Pillow (>=8.0.0), and OpenCV (>=4.5.0) for image processing and array operations.
• aiohttp (>=3.8.2) and asyncio (>=3.4.3) enable asynchronous downloading and workflow management for remote images.
• FastAPI, Uvicorn, python-multipart, and FastMCP support the web API layer in server.py but are not required for standalone depth estimation.
• All dependencies are declared in requirements.txt at the repository root.
• The generate_depth_map function in relief.py (lines 25-49) implements the core algorithm using these libraries.

Frequently Asked Questions

What are the minimum dependencies needed to run depth estimation without the web server?

You need only NumPy (>=1.20.0), Pillow (>=8.0.0), and OpenCV (>=4.5.0). These three libraries power the generate_depth_map function in relief.py. The FastAPI, Uvicorn, and FastMCP packages are only required if you intend to run the HTTP API server defined in server.py.

Why does the depth estimation pipeline require both Pillow and OpenCV?

Pillow handles the initial image loading, format detection, and grayscale conversion, returning a standardized Image object. OpenCV provides optimized computer vision functions such as Gaussian blur and resizing operations that process the NumPy array representation of the image. The pipeline leverages Pillow for I/O consistency and OpenCV for algorithmic processing.

How does aiohttp integrate with the depth estimation workflow?

aiohttp enables the high-level relief function to accept remote URLs as input_image_path arguments. Before the depth processing begins, the library asynchronously downloads the image data without blocking the event loop. This integration allows the pipeline to handle cloud-hosted images efficiently while maintaining responsive performance in async applications.

Where are the dependency versions specified in the repository?

All dependency constraints are declared in the requirements.txt file located at the root of the bigchx/mcp_3d_relief repository. This file pins minimum versions for NumPy, Pillow, OpenCV, aiohttp, asyncio, FastAPI, Uvicorn, python-multipart, and FastMCP. You can install the complete environment by running pip install -r requirements.txt in the project directory.

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