3D Mesh to Layered Curves Web App

Overview

This project provides a modern, web-based interface for the mesh simplification tool. Users can upload a 3D model file (.obj, .stl, .3mf), and the application will generate a .dxf file containing a series of simplified, layered 2D profiles suitable for use in CAD/CAM software.

The application features a modern UI with real-time progress updates, configurable processing parameters, and persistent job management. It is designed with an asynchronous worker architecture for robust background processing.

Architecture

This project is a single-container application built with a multi-stage Dockerfile and consists of:

• Frontend: A React single-page application built with create-react-app. It provides the user interface for uploading files, monitoring progress, and managing jobs. It communicates with the backend via HTTP requests and WebSockets.
• Backend: A FastAPI (Python) application. It handles:
  • File uploads and processing parameters.
  • Enqueuing processing jobs to a file-based job queue.
  • Serving API endpoints for managing job status (list, retrieve, delete).
  • Serving the static frontend files directly in production.
• Worker: A separate Python process (worker.py) that runs alongside the FastAPI app. It monitors the job queue, picks up jobs, processes the mesh, and updates job status and progress (which the frontend fetches via APIs/WebSockets).

Prerequisites

• Docker (for containerized deployment)
• For local development: Node.js and npm, Python 3.10+

How to Run the Application

1. Build the Docker Image

From the root of the project, run the following command to build the application image:

docker build -t mesh-app .

This may take a few minutes the first time as it downloads base images and installs all frontend and backend dependencies.

2. Run the Container

Once the image is built, run it with this command, making sure to use an absolute path to your data directory:

docker run --rm -p 8000:8000 -v "/path/to/your/data/directory:/app/data" mesh-app

• --rm: Automatically removes the container when it is stopped.
• -p 8000:8000: Maps port 8000 on your local machine to port 8000 inside the container.
• -v "/path/to/your/data/directory:/app/data": Mounts a local directory (e.g., $(pwd)/data) into the container at /app/data. This is where uploaded files, processed outputs, and job metadata will be stored. Ensure this path exists and is absolute.

3. Access the Web Interface

Once the container is running, open your web browser and navigate to:

http://localhost:8000

4. Use the Application

1. Upload File: Select a mesh file (.obj, .stl, .3mf). Optionally, adjust the Number of Layers and Points per Layer for processing.
2. Start Processing: Click "Start Processing". The upload progress bar will move.
3. Monitor Jobs: A new job entry will appear in the "Job List" with its status, real-time progress, and messages. You can close and reopen the browser, and your jobs will persist.
4. Actions: For COMPLETE jobs, you can download the generated DXF file. For any job, you can delete it.

5. Stopping the Application

To stop the application, press Ctrl+C in the terminal where the container is running.

Local Development

For active development, it's often easier to run the frontend, backend API, and worker processes directly on your local machine. This allows for live reloading of code changes.

1. Run the Development Script

A helper script is provided to automate the entire setup process. From the root of the project, run:

# Make the script executable (only needed once)
chmod +x start_local_dev.sh

# Run the script
./start_local_dev.sh

This script will:

1. Set up a Python virtual environment for the backend.
2. Install all Python and npm dependencies for both services.
3. Start the backend API server at http://localhost:8000.
4. Start the asynchronous worker process.
5. Start the React frontend development server at http://localhost:3000 (which proxies API requests to port 8000).

Your browser should automatically open to http://localhost:3000. You can now edit the code in frontend/src or backend/app to see live updates.

To stop all servers, press Ctrl+C in the terminal where the script is running.

Project Structure

.
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py         # FastAPI app (API endpoints)
│   │   ├── models.py       # Pydantic models for job management
│   │   ├── processing.py   # Core mesh logic (generator for progress)
│   │   └── worker.py       # Asynchronous job processing worker
│   ├── tests/              # Unit tests for backend logic
│   ├── start.sh            # Script to start backend/worker in Docker
│   └── requirements.txt
├── data/
│   └── (contains original model, and will store uploads/outputs/job_metadata/job_queue)
├── frontend/
│   ├── public/             # React public assets
│   ├── src/                # React source code (App.js, JobItem, JobWatcher etc.)
│   └── package.json
├── Dockerfile              # Production Docker build (single image)
└── start_local_dev.sh      # Local development setup and start script