0
# File Operations
1

2
STL file loading, saving, and format conversion with support for both ASCII and binary formats, automatic format detection, and multi-file operations.
3

4
## Capabilities
5

6
### Loading STL Files
7

8
Load mesh data from STL files with automatic format detection and various loading options.
9

10
```python { .api }
11
@classmethod
12
def from_file(
13
    cls,
14
    filename,
15
    calculate_normals=True,
16
    fh=None,
17
    mode=Mode.AUTOMATIC,
18
    speedups=True,
19
    **kwargs
20
):
21
    """
22
    Load a mesh from an STL file.
23

24
    Parameters:
25
    - filename (str): Path to the STL file to load
26
    - calculate_normals (bool): Whether to calculate normals automatically
27
    - fh (file, optional): File handle to use instead of opening filename
28
    - mode (Mode): File format mode (AUTOMATIC, ASCII, or BINARY)
29
    - speedups (bool): Whether to use Cython optimizations
30
    - **kwargs: Additional arguments passed to Mesh constructor
31

32
    Returns:
33
    Mesh: Loaded mesh object
34
    """
35

36
# Legacy alias for backward compatibility
37
StlMesh = Mesh.from_file
38
```
39

40
### Saving STL Files
41

42
Save mesh data to STL files with format control and normal updates.
43

44
```python { .api }
45
def save(self, filename, fh=None, mode=Mode.AUTOMATIC, update_normals=True):
46
    """
47
    Save the mesh to an STL file.
48

49
    Parameters:
50
    - filename (str): Output file path (required for STL headers)
51
    - fh (file, optional): File handle to write to instead of creating file
52
    - mode (Mode): Output format mode
53
    - update_normals (bool): Whether to recalculate normals before saving
54

55
    Notes:
56
    - AUTOMATIC mode writes ASCII to TTY, binary otherwise
57
    - File handles must be opened in binary mode even for ASCII files
58
    """
59
```
60

61
### Multi-File Operations
62

63
Load multiple meshes from single files or combine multiple files into one mesh.
64

65
```python { .api }
66
@classmethod
67
def from_multi_file(
68
    cls,
69
    filename,
70
    calculate_normals=True,
71
    fh=None,
72
    mode=Mode.AUTOMATIC,
73
    speedups=True,
74
    **kwargs
75
):
76
    """
77
    Load multiple meshes from a single STL file.
78

79
    Parameters:
80
    - filename (str): Path to multi-mesh STL file
81
    - calculate_normals (bool): Whether to calculate normals
82
    - fh (file, optional): File handle to use
83
    - mode (Mode): File format mode (hardcoded to ASCII for multi-mesh)
84
    - speedups (bool): Whether to use Cython optimizations
85
    - **kwargs: Additional arguments for Mesh constructor
86

87
    Yields:
88
    Mesh: Individual mesh objects from the file
89

90
    Notes:
91
    - Only ASCII STL files support multiple meshes
92
    - Binary STL format is limited to single meshes
93
    """
94

95
@classmethod
96
def from_files(
97
    cls,
98
    filenames,
99
    calculate_normals=True,
100
    mode=Mode.AUTOMATIC,
101
    speedups=True,
102
    **kwargs
103
):
104
    """
105
    Load and combine multiple STL files into a single mesh.
106

107
    Parameters:
108
    - filenames (list[str]): List of STL file paths to combine
109
    - calculate_normals (bool): Whether to calculate normals
110
    - mode (Mode): File format mode
111
    - speedups (bool): Whether to use Cython optimizations
112
    - **kwargs: Additional arguments for Mesh constructor
113

114
    Returns:
115
    Mesh: Combined mesh containing all triangles from input files
116
    """
117
```
118

119
### 3MF File Support
120

121
Load meshes from 3D Manufacturing Format (3MF) files.
122

123
```python { .api }
124
@classmethod
125
def from_3mf_file(cls, filename, calculate_normals=True, **kwargs):
126
    """
127
    Load meshes from a 3MF file.
128

129
    Parameters:
130
    - filename (str): Path to the 3MF file
131
    - calculate_normals (bool): Whether to calculate normals
132
    - **kwargs: Additional arguments for Mesh constructor
133

134
    Yields:
135
    Mesh: Individual mesh objects found in the 3MF file
136

137
    Notes:
138
    - 3MF files are ZIP archives containing XML model definitions
139
    - Automatically extracts vertices and triangles from 3D model data
140
    """
141
```
142

143
### Low-Level File I/O
144

145
Direct file loading with format control for advanced use cases.
146

147
```python { .api }
148
@classmethod
149
def load(cls, fh, mode=Mode.AUTOMATIC, speedups=True):
150
    """
151
    Load mesh data from an open file handle.
152

153
    Parameters:
154
    - fh (file): Open file handle positioned at start of STL data
155
    - mode (Mode): File format mode for loading
156
    - speedups (bool): Whether to use Cython optimizations
157

158
    Returns:
159
    tuple[bytes, numpy.array]: (mesh_name, mesh_data) tuple
160

161
    Notes:
162
    - Low-level interface used by from_file methods
163
    - Automatically detects ASCII vs binary format when mode is AUTOMATIC
164
    - Returns raw mesh data as NumPy structured array
165
    """
166
```
167

168
## Usage Examples
169

170
### Basic File Loading and Saving
171

172
```python
173
from stl import mesh
174

175
# Load an STL file
176
my_mesh = mesh.Mesh.from_file('input.stl')
177

178
# Save to binary format
179
my_mesh.save('output_binary.stl', mode=mesh.Mode.BINARY)
180

181
# Save to ASCII format  
182
my_mesh.save('output_ascii.stl', mode=mesh.Mode.ASCII)
183
```
184

185
### Combining Multiple Files
186

187
```python
188
from stl import mesh
189

190
# Combine multiple STL files into one mesh
191
filenames = ['part1.stl', 'part2.stl', 'part3.stl']
192
combined_mesh = mesh.Mesh.from_files(filenames)
193

194
# Save the combined result
195
combined_mesh.save('combined_model.stl')
196
```
197

198
### Working with File Handles
199

200
```python
201
from stl import mesh
202
import io
203

204
# Load from file handle
205
with open('model.stl', 'rb') as f:
206
    my_mesh = mesh.Mesh.from_file('model.stl', fh=f)
207

208
# Save to bytes buffer
209
buffer = io.BytesIO()
210
my_mesh.save('mesh.stl', fh=buffer)
211
stl_bytes = buffer.getvalue()
212
```
213

214
### Multi-Mesh Files
215

216
```python
217
from stl import mesh
218

219
# Load multiple meshes from a single ASCII STL file
220
for individual_mesh in mesh.Mesh.from_multi_file('multi_part.stl'):
221
    print(f"Loaded mesh: {individual_mesh.name}")
222
    print(f"Triangle count: {len(individual_mesh)}")
223
```
224

225
## Error Handling
226

227
- **RuntimeError**: Raised for corrupted STL data or format errors
228
- **AssertionError**: Raised when file size doesn't match header count
229
- **TypeError**: Raised when file handle is opened in text mode instead of binary
230
- **OSError**: Handled gracefully for file access issues