geometry.load — Import a geometry file as a typed geometry.Asset.
asset = geometry.load(path) reads a local geometry file, imports it, and returns a host geometry.Asset; asset = geometry.load(path, 'Units', unit) also sets the length unit of the asset's coordinates.
Syntax
asset = geometry.load(path, Name, Value)Inputs
path- Type
StringScalar- Required
- Yes
- Default
- —
- Description
- Scalar path to an importable geometry file.
Name, Value- Type
Any- Required
- Variadic
- Default
- —
- Description
- Optional 'Units' and 'm', 'mm', or 'in': the source unit when the file declares none.
Returns
asset- Type
Any- Description
- Host geometry.Asset object.
Errors
RunMat:geometry:load:InvalidPath- When
- The path is not scalar string text or a character row, or an option is not a supported Units Name, Value pair.
- Message
geometry.load: invalid path
RunMat:geometry:load:IoFailure- When
- The geometry file cannot be read.
- Message
geometry.load: failed to read geometry file
RunMat:geometry:load:OperationFailed- When
- The geometry importer rejects or cannot import the file.
- Message
geometry.load: operation failed
Input and result
path is scalar text. The result is a geometry.Asset with source, revision, unit, mesh, region, and mapping metadata; the imported payload is retained so that geometry.region, geometry.listRegions, geometry.meshes, mesh(asset), and meshing.generate can use it. The asset records the SHA-256 of the bytes it was imported from.
STEP, IGES, and BREP import as exact CAD through the native OCCT importer, with one region per face (face_000001, face_000002, ...). Without OCCT, STEP is imported metadata-only: exchange facts are available but there is no topology or render mesh. STL, OBJ, PLY, and glTF import through the portable mesh importer as a single region_default region.
Units
The only option is 'Units', which sets the length unit of the asset's coordinates: 'm' (the default), 'mm', or 'in'. The longer spellings 'meter', 'meters', 'metre', 'metres', 'millimeter', 'millimeters', 'millimetre', 'millimetres', 'inch', and 'inches' are also accepted, and matching is case-insensitive. Give the option at most once.
Formats that do not declare a unit (BREP, STL, OBJ, PLY, and glTF) are read as being in that unit. STEP files declare their own units, and the declared unit always governs how the file is read; the geometry is then expressed in the requested unit. The unit in effect is reported in asset.units as 'meter', 'millimeter', or 'inch'.
Meshing and analysis work in SI units. meshing.generate re-reads the source with the asset's unit, so a BREP or other undeclared-unit file modeled in millimeters must be loaded with 'Units', 'mm' to mesh at the right scale.
Use in a study
The asset is the geometry of a script-built study: select regions with geometry.region, assemble a model with fea.model, generate a solver mesh with meshing.generate, and bind them with fea.study, always on the same asset so that region references and the mesh share one geometry revision.
Effects and errors
Reading the file can suspend and requires filesystem access. The import checks cancellation, and a failed import returns no asset. Browser execution needs an available filesystem bridge and a supported importer.
RunMat:geometry:load:InvalidPath reports a path that is not scalar text and an invalid option: options that are not Name, Value pairs, a name other than Units, a repeated Units, or an unsupported unit. RunMat:geometry:load:IoFailure reports a file that cannot be read, RunMat:geometry:load:OperationFailed an importer rejection, RunMat:geometry:load:Internal a result that cannot be converted, and RunMat:geometry:load:TooManyOutputs a request for more than one output.
Examples
Import a triangle STL
asset = geometry.load('part.stl');
class(asset)Expected output:
ans = geometry.AssetImport an STL modeled in millimeters
asset = geometry.load('part.stl', 'Units', 'mm');
asset.unitsImport an exact CAD solid and list its faces
part = geometry.load('box.brep', 'Units', 'm');
firstFace = part.regions{1};
firstFace.region_idUnsupported units are rejected before the file is imported
asset = geometry.load('part.stl', 'Units', 'ft');Using geometry.load with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how geometry.load changes the result.
Run a small geometry.load example, explain the result, then change one input and compare the output.
FAQ
Does load always need native CAD support?⌄
No. Mesh formats such as STL import portably. STEP, IGES, and BREP need the native OCCT importer for exact topology, which analysis and meshing require.
My STEP file is in millimeters. Do I need 'Units'?⌄
No. STEP declares its units and they are always honored. 'Units' matters for files without a declaration, such as BREP and STL.
Related Geometry functions
Triangulation
DelaunayTri · DelaunayTri.freeBoundary · DelaunayTri.nearestNeighbor · DelaunayTri.pointLocation · freeBoundary · nearestNeighbor · pointLocation
Construction
geometry.box · geometry.chamfer · geometry.cylinder · geometry.edges · geometry.edgesIntroducedBy · geometry.extrude · geometry.faces · geometry.facesIntroducedBy · geometry.fillet · geometry.finish · geometry.hole · geometry.instance · geometry.intersect · geometry.pocket · geometry.revolve · geometry.solid · geometry.sphere · geometry.subtract · geometry.transform · geometry.union · geometry.withRegion
Related guides
Source you can read
Every RunMat function's source is public. Read exactly how geometry.load is executed, line by line, in Rust.
- View the source for geometry.load in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.