AdMesh Docker Scripts

A Docker-based wrapper for AdMesh, a tool for processing and repairing STL files commonly used in 3D printing.

Overview

This project provides a convenient Docker containerized version of AdMesh along with helper scripts to easily fix and process STL files without needing to install AdMesh directly on your system.

Features

• 🐳 Dockerized AdMesh: No need to install AdMesh locally
• 🔧 Automated STL Repair: Simple script to fix common STL file issues
• 📁 Batch Processing: Easy to integrate into workflows
• 🚀 CI/CD Ready: Automated Docker image builds via Forgejo Actions

Quick Start

Using the Fix Script

The easiest way to repair an STL file is using the provided fix.sh script:

# Make the script executable
chmod +x fix.sh

# Fix an STL file
./fix.sh path/to/your-model.stl

This will create a repaired file named your-model-admesh-fixed.stl in the same directory.

Using Docker Directly

You can also use the Docker image directly:

# Pull the image
docker pull forgejo.gitx.codes/xtream1101/admesh-scripts:latest

# Run admesh with your STL file
docker run --rm -v /path/to/your-file.stl:/input.stl \
  -v /path/to/output.stl:/output.stl \
  forgejo.gitx.codes/xtream1101/admesh-scripts:latest \
  --write-binary=/output.stl /input.stl

What AdMesh Does

AdMesh is a program for processing triangulated solid meshes. It can:

• Repair STL files: Fix common issues like holes, non-manifold edges, and degenerate facets
• Convert formats: Transform between ASCII and binary STL formats
• Optimize meshes: Remove duplicate vertices and fix winding
• Analyze geometry: Provide statistics about your 3D models
• Transform models: Scale, rotate, translate, and mirror meshes

Installation

Option 1: Use Pre-built Docker Image

docker pull forgejo.gitx.codes/xtream1101/admesh-scripts:latest

Option 2: Build from Source

# Clone the repository
git clone <repository-url>
cd admesh

# Build the Docker image
docker build -t admesh .

Usage Examples

Basic STL Repair

# Repair a broken STL file
./fix.sh broken-model.stl

Advanced Usage with Docker

# Get help and see all available options
docker run --rm forgejo.gitx.codes/xtream1101/admesh-scripts:latest --help

# Check STL file statistics
docker run --rm -v $(pwd)/model.stl:/input.stl \
  forgejo.gitx.codes/xtream1101/admesh-scripts:latest /input.stl

# Convert ASCII STL to binary
docker run --rm -v $(pwd)/input.stl:/input.stl \
  -v $(pwd)/output.stl:/output.stl \
  forgejo.gitx.codes/xtream1101/admesh-scripts:latest \
  --write-binary=/output.stl /input.stl

# Fix and scale a model
docker run --rm -v $(pwd)/input.stl:/input.stl \
  -v $(pwd)/output.stl:/output.stl \
  forgejo.gitx.codes/xtream1101/admesh-scripts:latest \
  --scale=2.0 --write-binary=/output.stl /input.stl

Fix Script Options

The fix.sh script provides the following features:

• Input validation: Checks if the file exists and has a .stl extension
• Automatic output naming: Creates files with -admesh-fixed suffix
• Error handling: Provides clear error messages and exit codes
• Path resolution: Works with relative and absolute paths

Script Usage

./fix.sh <path-to-stl-file>

# Examples:
./fix.sh model.stl                    # Fix model.stl
./fix.sh /home/user/3d-models/part.stl # Fix with absolute path
./fix.sh ../models/broken.stl         # Fix with relative path

File Structure

.
├── Dockerfile              # Docker image definition
├── fix.sh                  # STL repair helper script
├── README.md               # This file
└── .forgejo/
    └── workflows/
        └── build.yaml       # CI/CD pipeline for building Docker images

Development

Building the Image

docker build -t admesh .

Testing

# Test with a sample STL file
./fix.sh test-model.stl

# Verify the output
ls -la *admesh-fixed.stl

CI/CD

This project uses Forgejo Actions for automated builds. The workflow:

1. Installs Docker in the CI environment
2. Sets up Docker Buildx for advanced builds
3. Logs into the container registry
4. Builds and pushes the Docker image

The image is automatically built and pushed to forgejo.gitx.codes/xtream1101/admesh-scripts:latest on every commit.

Troubleshooting

Common Issues

1. Permission denied when running fix.sh:

   chmod +x fix.sh
   

2. Docker not found: Make sure Docker is installed and running on your system.

3. File not found errors: Ensure you're providing the correct path to your STL file.

4. Output file not created: Check that you have write permissions in the output directory.

Related Projects

• AdMesh - The original STL processing tool
• Meshlab - Advanced 3D mesh processing
• OpenSCAD - Parametric 3D modeling