# stl_handler

**Repository Path**: tong_yan_jun/stl_handler

## Basic Information

- **Project Name**: stl_handler
- **Description**: OpenFOAM中尝尝有用到ASCII格式的STL，需要这些STL进行一些简单的处理and可视化；
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# STL Handler for cfMesh

A Python CLI and library for STL file manipulation in cfMesh meshing workflows.

## Features

- **Binary ↔ ASCII Conversion**: Convert between STL formats while preserving face boundaries
- **Face Management**: List, delete, and rename solid block faces
- **STL Merging**: Combine multiple STL files into one
- **Geometry Transforms**: Translate, rotate, and scale meshes
- **Browser Visualization**: View 3D meshes with face coloring

## Installation

```bash
pip install -e .
```

## CLI Usage

### View STL Info
```bash
stl-handler info input.stl
```

### Convert Format
```bash
stl-handler convert input.stl output.stl --format ascii
stl-handler convert input.stl output.stl --format binary
```

### List Faces
```bash
stl-handler faces input.stl
```

### Delete Faces
```bash
stl-handler delete input.stl output.stl --faces wall,inlet
stl-handler delete input.stl output.stl --interactive
```

### Rename Faces
```bash
stl-handler rename input.stl output.stl --map "wall=boundary1,inlet=boundary2"
```

### Merge STL Files
```bash
stl-handler merge output.stl part1.stl part2.stl part3.stl
```

### Geometry Transforms
```bash
stl-handler transform input.stl output.stl --translate 10,0,0
stl-handler transform input.stl output.stl --rotate z 90
stl-handler transform input.stl output.stl --scale 2
stl-handler transform input.stl output.stl --translate 5,5,5 --scale 2 --rotate z 45
```

### View in Browser
```bash
stl-handler view input.stl
```

## Python API

```python
from stl_handler import read_stl, write_stl, STLFormat
from stl_handler.operations import delete_faces, rename_face, merge_meshes, translate, scale, rotate

mesh = read_stl("input.stl")

print(f"Faces: {mesh.face_count}")
print(f"Triangles: {mesh.triangle_count}")

for face in mesh.faces:
    print(f"  {face.name}: {face.triangle_count} triangles")

new_mesh = delete_faces(mesh, ["wall"])
write_stl(new_mesh, "output.stl", STLFormat.ASCII)
```

## cfMesh Compatibility

ASCII STL output uses `solid name ... endsolid name` blocks for boundary face identification:

```
solid wall
  facet normal 0.0 0.0 1.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 1.0 0.0 0.0
      vertex 0.0 1.0 0.0
    endloop
  endfacet
endsolid wall
```

Binary STL files do not preserve face names; all triangles are grouped into a single "unnamed" face.

## Running Tests

```bash
pytest tests/ -v
```

## Requirements

- Python 3.10+
- numpy
- trimesh
- click
- questionary