File Operations

@classmethod
def from_file(
    cls,
    filename,
    calculate_normals=True,
    fh=None,
    mode=Mode.AUTOMATIC,
    speedups=True,
    **kwargs
):
    """
    Load a mesh from an STL file.

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

    Returns:
    Mesh: Loaded mesh object
    """

# Legacy alias for backward compatibility
StlMesh = Mesh.from_file

def save(self, filename, fh=None, mode=Mode.AUTOMATIC, update_normals=True):
    """
    Save the mesh to an STL file.

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

    Notes:
    - AUTOMATIC mode writes ASCII to TTY, binary otherwise
    - File handles must be opened in binary mode even for ASCII files
    """

@classmethod
def from_multi_file(
    cls,
    filename,
    calculate_normals=True,
    fh=None,
    mode=Mode.AUTOMATIC,
    speedups=True,
    **kwargs
):
    """
    Load multiple meshes from a single STL file.

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

    Yields:
    Mesh: Individual mesh objects from the file

    Notes:
    - Only ASCII STL files support multiple meshes
    - Binary STL format is limited to single meshes
    """

@classmethod
def from_files(
    cls,
    filenames,
    calculate_normals=True,
    mode=Mode.AUTOMATIC,
    speedups=True,
    **kwargs
):
    """
    Load and combine multiple STL files into a single mesh.

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

    Returns:
    Mesh: Combined mesh containing all triangles from input files
    """

@classmethod
def from_3mf_file(cls, filename, calculate_normals=True, **kwargs):
    """
    Load meshes from a 3MF file.

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

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

    Notes:
    - 3MF files are ZIP archives containing XML model definitions
    - Automatically extracts vertices and triangles from 3D model data
    """

@classmethod
def load(cls, fh, mode=Mode.AUTOMATIC, speedups=True):
    """
    Load mesh data from an open file handle.

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

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

    Notes:
    - Low-level interface used by from_file methods
    - Automatically detects ASCII vs binary format when mode is AUTOMATIC
    - Returns raw mesh data as NumPy structured array
    """

from stl import mesh

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

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

# Save to ASCII format  
my_mesh.save('output_ascii.stl', mode=mesh.Mode.ASCII)

from stl import mesh

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

# Save the combined result
combined_mesh.save('combined_model.stl')

from stl import mesh
import io

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

# Save to bytes buffer
buffer = io.BytesIO()
my_mesh.save('mesh.stl', fh=buffer)
stl_bytes = buffer.getvalue()

from stl import mesh

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