asset3d.read

R2026b

Read 3D asset from file

Since R2026b

Syntax

result = asset3d.read(filename)

result = asset3d.read(filename,Name=Value)

Description

Add-On Required: This feature requires the 3D Asset Processing Library for MATLAB add-on.

result = asset3d.read(filename) reads the specified file and returns a 3D asset mesh or scene. The function automatically detects the file format from the file extension.

result = asset3d.read(filename,Name=Value) specifies one or more options using name-value arguments. For example, ReadAs="mesh" forces the function to return a Mesh object regardless of the file contents.

Examples

Read Single Mesh from File

Create a simple pyramid mesh, write it to an FBX file, and read it back using the asset3d.read function. Then, inspect the geometric properties of the imported mesh and display it in a figure.

Create a temporary folder for your asset files.

tmpDir = fullfile(tempdir,"asset3dReadExamples");
if ~isfolder(tmpDir)
    mkdir(tmpDir)
end

Define a simple pyramid mesh.

vertices = [0 0 0; 1 0 0; 1 1 0; 0 1 0; 0.5 0.5 1];
faces = [1 2 5; 2 3 5; 3 4 5; 4 1 5; 1 3 4; 1 2 3];
srcMesh = asset3d.Mesh(vertices,faces);

Write the mesh to an FBX file.

fbxFile = fullfile(tmpDir,"pyramid.fbx");
asset3d.write(srcMesh,fbxFile,UpAxis="Z")

Read the FBX file. Because the file contains one mesh, asset3d.read returns a Mesh object.

mesh = asset3d.read(fbxFile)

mesh = 
  Mesh with properties:

         Vertices: [5×3 double]
            Faces: [6×3 double]
      FaceNormals: [6×3 double]
    VertexNormals: [5×3 double]
           UpAxis: "Z"

           Bounds: [2×3 double]
         Centroid: [0.5000 0.5000 0.2303]
          Extents: [1 1 1]
             Area: 3.2361
           Volume: 0.3333
     IsWatertight: 1

       FaceColors: []
     VertexColors: []
               UV: [0×2 double]
         Material: [1×1 asset3d.Material]

Inspect the axis-aligned bounding box limits of the imported mesh.

mesh.Bounds

ans = 2×3

    0    0    0
    1    1    1

Display the original mesh and the imported mesh side by side.

figure

subplot(1,2,1)
patch(srcMesh,FaceColor=[0.2 0.55 0.85],EdgeColor="k")
axis equal
view(3)
grid on
title("Original Mesh")

subplot(1,2,2)
patch(mesh,FaceColor=[0.2 0.55 0.85],EdgeColor="k")
axis equal
view(3)
grid on
title("Imported Mesh")

Read Multi-Part Scene File as Single Mesh

Build a two-part scene from simple box meshes, write it to a GLB file, and read it back as a single flattened mesh using name-value arguments. Then, inspect the properties of the imported mesh and display it in a figure.

Create a temporary folder for your asset files.

tmpDir = fullfile(tempdir,"asset3dReadExamples");
if ~isfolder(tmpDir)
    mkdir(tmpDir)
end

Define the vertices and faces for a box.

boxVertices = [-0.5 -0.5 -0.5; 0.5 -0.5 -0.5; 0.5 0.5 -0.5; -0.5 0.5 -0.5; -0.5 -0.5 0.5; 0.5 -0.5 0.5; 0.5 0.5 0.5; -0.5 0.5 0.5];
boxFaces = [1 2 3; 1 3 4; 5 8 7; 5 7 6; 1 5 6; 1 6 2; 2 6 7; 2 7 3; 3 7 8; 3 8 4; 4 8 5; 4 5 1];

Create a body mesh and a sensor mesh, with distinct face colors.

blueFaces = repmat(uint8([70 140 230]),size(boxFaces,1),1);
orangeFaces = repmat(uint8([230 150 60]),size(boxFaces,1),1);
bodyMesh = asset3d.Mesh(boxVertices,boxFaces,FaceColors=blueFaces);
sensorMesh = asset3d.Mesh(boxVertices,boxFaces,FaceColors=orangeFaces);

Scale each mesh to the desired dimensions.

scale(bodyMesh,[3 1.5 1])
scale(sensorMesh,[0.6 0.6 0.6])

Create a scene, and add the body mesh.

sceneOut = asset3d.Scene;
addMesh(sceneOut,bodyMesh,Name="Body",NodeName="body")

Place the sensor mesh on top of the body mesh using a transform.

T = eye(4);
T(1:3,4) = [0; 0; 0.8];
addMesh(sceneOut,sensorMesh,Name="Sensor",NodeName="sensor",ParentNodeName="body",Transform=T)

Write the scene to a GLB file.

sceneFile = fullfile(tmpDir,"twoPartScene.glb");
asset3d.write(sceneOut,sceneFile,FileType="glb")

Read the file into the workspace as a single mesh. Specifying the ReadAs argument as "mesh" flattens the scene graph into one Mesh object, while specifying UpAxis as "auto" preserves the native axis orientation of the file.

importedMesh = asset3d.read(sceneFile,FileType="glb",ReadAs="mesh",UpAxis="auto")

importedMesh = 
  Mesh with properties:

         Vertices: [72×3 double]
            Faces: [24×3 double]
      FaceNormals: [24×3 double]
    VertexNormals: [72×3 double]
           UpAxis: "Y"

           Bounds: [2×3 double]
         Centroid: [0 0 0.0857]
          Extents: [3 1 1.8500]
             Area: 20.1600
           Volume: 4.7160
     IsWatertight: 0

       FaceColors: []
     VertexColors: [72×4 uint8]
               UV: [0×2 double]
         Material: []

Display the original scene and the imported mesh side by side.

figure

subplot(1,2,1)
patch(sceneOut,EdgeColor="k")
axis equal
view(3)
grid on
title("Original Scene")

subplot(1,2,2)
patch(importedMesh,EdgeColor="k")
axis equal
view(3)
grid on
title("Scene Imported as Mesh")

Input Arguments

filename — 3D asset file path

string scalar

Path to the 3D asset file, specified as a string scalar. The function supports these file formats: GLB, GLTF, OBJ, STL, PLY, OFF, DAE, 3MF, FBX, USD, USDA, USDC, and USDZ. The function automatically detects the file format from the file extension. To override the detected format, specify the FileType name-value argument.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: asset3d.read(filename,ReadAs="mesh",UpAxis="auto") reads an asset file, returns its geometries as a single mesh, and preserves the up-axis convention of the file.

FileType — File format override

"" (default) | "stl" | "obj" | "ply" | "off" | "glb" | "gltf" | "dae" | "3mf" | "fbx" | "usd" | "usda" | "usdc" | "usdz"

File format override, specified as one of these options: "stl", "obj", "ply", "off", "glb", "gltf", "dae", "3mf", "fbx", "usd", "usda", "usdc", or "usdz". The function uses this value instead of the file extension when it detects the input format.

ReadAs — Returned object type

"auto" (default) | "mesh" | "scene"

Returned object type, specified as "auto", "mesh", or "scene". By default, the function uses:

• "auto" — The function returns a Mesh object if the file contains a single geometry, or a Scene object if it contains multiple geometries or a scene graph.

• "mesh" — The function returns all geometries in the file flattened to a single Mesh object.

• "scene" — The object returns a Scene object regardless of the number of geometries present in the file.

UpAxis — Up-axis convention for loaded asset

"auto" (default) | "Z" | "X" | "Y"

Up-axis convention for the loaded asset, specified as "auto", "X", "Y", or "Z". If this value is "auto", the native up-axis convention of the input format or defined in the file metadata.

• STL files — The function uses Z-up.

• GLB, GLTF, DAE, OBJ, PLY, OFF, and 3MF files — The function uses Y-up.

• FBX, USD, USDA, USDC, and USDZ — The function uses the metadata value. If the metadata is empty, it uses Y-up.

Specify "X", "Y", or "Z" to convert the loaded asset to the selected convention by transforming the vertices.

Output Arguments

result — Imported 3D asset

Mesh object | Scene object

Imported 3D asset, returned as a Mesh or Scene object.

The object returned depends on the file contents or the ReadAs name-value argument:

• Mesh object — The file contains one mesh, or the value of ReadAs is "mesh".

• Scene object — The file contains multiple geometries or a scene graph, or the value of ReadAs is "mesh".

Version History

Introduced in R2026b