asset3d.write

R2026b

Write 3D asset to file

Since R2026b

collapse all in page

Syntax

asset3d.write(obj,filename)
asset3d.write(obj,filename,Name=Value)

Description

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

asset3d.write(obj,filename) writes the 3D asset object obj to the file filename. The function uses the specified file extension to determine the output format.

example

asset3d.write(obj,filename,Name=Value) specifies one or more export options using name-value arguments. For example, FileType="glb" exports to GLB file instead of the format indicated by the file extension.

Examples

collapse all

This example uses:

Open Live Script

Create a mesh, modify its size and position, and write the result to an FBX file. Then, read the file back to confirm the exported geometry.

Create a temporary folder for your asset files.

tmpDir = fullfile(tempdir,"asset3dWriteExamples");
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];
meshObj = asset3d.Mesh(vertices,faces);

Scale and translate the mesh before exporting it.

scale(meshObj,[2 1.5 1])
translate(meshObj,[1 0 0])

Write the transformed mesh to an FBX file using a Z-up convention.

fbxFile = fullfile(tmpDir,"transformedPyramid.fbx");
asset3d.write(meshObj,fbxFile,UpAxis="Z")

Read the asset from the exported file back into the workspace, and inspect the result.

exportedMesh = asset3d.read(fbxFile)
exportedMesh = 
  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: [2 0.7500 0.2021]
          Extents: [2 1.5000 1]
             Area: 7.6213
           Volume: 1
     IsWatertight: 1

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

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

exportedMesh.Bounds
ans = 2×3

    1.0000         0         0
    3.0000    1.5000    1.0000

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

figure

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

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

This example uses:

Open Live Script

Create a two-part scene and export it to a GLB file. Use the FileType argument to specify the output format and the UpAxis argument to control the axis convention used in the exported file.

Create a temporary folder for the asset files.

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

Define the vertices and faces for a box mesh.

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 different sizes and 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);
bodyMesh = scale(bodyMesh,[3 1.5 1]);
sensorMesh = scale(sensorMesh,[0.6 0.6 0.6]);

Assemble the meshes into a scene.

sceneOut = asset3d.Scene;
addMesh(sceneOut,bodyMesh,Name="Body",NodeName="body")
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.

glbFile = fullfile(tmpDir,"vehicleScene.glb");
asset3d.write(sceneOut,glbFile,FileType="glb",UpAxis="Z")

Read the scene from the exported file back into the workspace and inspect it.

exportedScene = asset3d.read(glbFile)
exportedScene = 
  Scene with properties:

    Geometry: dictionary (string ⟼ asset3d.Mesh) with 2 entries
       Graph: [1×1 struct]
      UpAxis: "Y"

      Bounds: [2×3 double]
    Centroid: [0 0 0.3000]
     Extents: [3 1.5000 1.6000]
        Area: 20.1600
      Volume: 4.7160

Display the scene graph structure of the scene.

dispGraph(exportedScene)
world
    ├── body [Mesh: 12 faces]
    └── sensor [Mesh: 12 faces]

Display the original scene and the exported scene 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(exportedScene,EdgeColor="k")
axis equal
view(3)
grid on
title("Exported Scene")

Input Arguments

collapse all

3D asset to export, specified as a Mesh or Scene object.

Output file path, specified as a string scalar. The function supports these file formats for writing: STL, OBJ, PLY, OFF, GLB, GLTF, DAE, 3MF, FBX, USD, USDA, USDC, USDZ, and URDF. The function infers the file format from the file extension. To override the inferred format, use the FileType name-value argument.

Name-Value Arguments

collapse all

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.write(obj,filename,FileType="glb",UpAxis="Z") writes the asset in GLB format, and stores it using Z-up coordinates.

Output file type, specified as one of these options: "stl", "obj", "ply", "off", "glb", "gltf", "dae", "3mf", "fbx", "usd", "usda", "usdc", "usdz", or "urdf". The function uses this value instead of the file extension when it writes the output file. The function preserves color, material, and texture information for formats that inherently support these types of information.

Up-axis convention for the exported asset, specified as: "auto", "X", "Y", or "Z". If this value is "auto", the function applies the native up-axis convention of the target file format, such as Y-up for GLB and Z-up for STL. Specify "X", "Y", or "Z" to convert the asset to the selected convention before export.

Version History

Introduced in R2026b

See Also

| | | | |