3MF file format: core model

The 3D Model part is XML in the core namespace http://schemas.microsoft.com/3dmanufacturing/core/2015/02, written so that a simple forward-only parser can read it: every element is defined before anything refers to it. This page follows core specification 1.4.0. Attributes marked “any” in the schema may also carry attributes from extension namespaces, and extension elements may appear where the schema has an any slot.

Element tree

model
├── metadata           (zero or more)
├── resources
│   ├── basematerials
│   │   └── base       (one or more)
│   ├── (extension resources)
│   └── object         (one or more)
│       ├── metadatagroup
│       │   └── metadata
│       └── mesh  or  components
│           ├── vertices
│           │   └── vertex
│           ├── triangles
│           │   └── triangle
│           └── t:trianglesets
│               └── t:triangleset
│                   ├── t:ref
│                   └── t:refrange
│           (components)
│           └── component
└── build
    └── item           (zero or more)
        └── metadatagroup
            └── metadata

The core elements and where each may appear.

Simple types

Type	Values
`ST_Unit`	`micron`, `millimeter`, `centimeter`, `inch`, `foot`, `meter`
`ST_Number`	A decimal number with optional sign and exponent, such as `-1.5e3`; any precision
`ST_ResourceID`	Positive integer, 1 to 2³¹−1
`ST_ResourceIndex`	Non-negative integer, 0 to 2³¹−1
`ST_Matrix3D`	Twelve numbers separated by spaces (see below)
`ST_ColorValue`	`#RRGGBB` or `#RRGGBBAA` in hexadecimal, sRGB; alpha 00 transparent to FF opaque (the default)
`ST_UriReference`	An absolute part name starting with `/`
`ST_ObjectType`	`model`, `solidsupport`, `support`, `surface`, `other`

Coordinates and transforms

Coordinates are right-handed. The origin is the bottom-front-left corner of the printer’s build area: X increases to the right, Y towards the back and Z upwards. All lengths use the unit set on <model>.

A transform is a row-major 4×4 affine matrix whose last column is always 0, 0, 0, 1 and is not written. The attribute lists the other twelve values as m00 m01 m02 m10 m11 m12 m20 m21 m22 m30 m31 m32, so the translation is the last three. A point (x, y, z) becomes (x·m00 + y·m10 + z·m20 + m30, x·m01 + y·m11 + z·m21 + m31, x·m02 + y·m12 + z·m22 + m32). Matrices should not be singular. A transform with a negative determinant must not turn the shape inside out: the result keeps a positive volume. After all transforms the model should lie in the positive octant.

model

The root element; exactly one per 3D Model part. It holds optional metadata elements, then resources, then build.

Attribute	Type	Use	Default	Meaning
`unit`	ST_Unit	optional	millimeter	Unit of every coordinate and length
`xml:lang`	xs:language	optional		Default language of the content
`requiredextensions`	string	optional		Space-separated namespace prefixes of extensions a consumer must support; a consumer that lacks one must not edit or make the model
`recommendedextensions`	string	optional		Prefixes of extensions needed for the design intent; consumers should warn and ask. An extension cannot be both required and recommended

metadata and metadatagroup

Attribute	Type	Use	Meaning
`name`	xs:QName	required	A well-known name below, or a vendor name prefixed with a namespace declared on `<model>`
`preserve`	xs:boolean	optional	True: editors should keep the value even if they change what it describes (default false)
`type`	string	optional	A built-in XML Schema simple type for the value, such as `xs:string` (the default)

The element’s text is the value. Names must not repeat. Well-known names, used without a prefix on the model:

Name	Meaning
`Title`	Title of the document
`Designer`	Name of a designer
`Description`	Description of the document
`Copyright`	Copyright notice
`LicenseTerms`	Licence information
`Rating`	An industry rating
`CreationDate`	When a source application created it
`ModificationDate`	When it was last modified
`Application`	Name of the application that created it

<object> and <item> may each hold one <metadatagroup> of vendor <metadata> elements; these go with the element and are removed with it.

resources

A library of objects, materials and extension resources. Resource IDs must be unique across the whole model. Property groups (basematerials and the extension groups) come before the objects in the core schema.

object

Attribute	Type	Use	Default	Meaning
`id`	ST_ResourceID	required		Unique identifier
`type`	ST_ObjectType	optional	model	Function of the object; see below
`thumbnail`	ST_UriReference	optional		Part name of a JPEG or PNG object thumbnail
`partnumber`	string	optional		Part number, kept by editors as the object is changed or split
`name`	string	optional		Readable name
`pid`	ST_ResourceID	optional		Default property group (such as a `basematerials`); required when `pindex` is given
`pindex`	ST_ResourceIndex	optional		Zero-based index into that group: the object’s default property

An object holds either one <mesh> or one <components> (extensions add other shapes). If any triangle has its own property, the object must give pid and pindex as the default. Objects made of components must not have pid or pindex, and their type is ignored.

`type`	Meaning	Mesh rules
`model`	A solid part to make	Must be closed and manifold, consistently oriented, normals outwards; at least 4 triangles
`solidsupport`	A solid support structure	As model
`support`	A support structure the printer may draw as it chooses (never filled)	May be open
`surface`	An open surface	May be open
`other`	Not to be made; must never be reached from the build, directly or through components	May be open

Support objects should only appear as components alongside the model objects they support. Consumers may ignore or regenerate supports, but this is not recommended.

mesh, vertices and vertex

A mesh holds <vertices>, then <triangles>, then optional triangle sets. Fewer than 2³¹ vertices and triangles.

vertex attribute	Type	Use	Meaning
`x`	ST_Number	required	X coordinate
`y`	ST_Number	required	Y coordinate
`z`	ST_Number	required	Z coordinate

Vertices are numbered from 0 in the order written. Producers should not repeat vertices (unless merging would make edges non-manifold) and should merge vertices that are very close.

Mesh rules

Manifold edges: each edge of a triangle is shared, by vertex index, with exactly one other triangle.
Consistent orientation: two triangles sharing an edge list its vertices in opposite orders.
Outward normals: the normal of triangle ABC is the direction of (B − A) × (C − A), and it points away from the inside.
Self-intersections and degenerate (zero-area) triangles should be avoided, but consumers must accept them.
Fill rule: always “positive”. Cast a ray from a point; add one for each crossing from inside to outside and subtract one for the reverse. The point is inside if the total is one or more.
Overlapping order: where triangles overlap, the last one’s properties apply; if it has none, none apply.

triangles and triangle

Attribute	Type	Use	Meaning
`v1`, `v2`, `v3`	ST_ResourceIndex	required	Vertex indices, anticlockwise seen from outside; all three different
`p1`	ST_ResourceIndex	optional	Property index at the first vertex (overrides the object’s `pindex`)
`p2`, `p3`	ST_ResourceIndex	optional	Property indices at the second and third vertices; if either is missing, `p1` applies to the whole triangle
`pid`	ST_ResourceID	optional	Property group for this triangle (overrides the object’s `pid`)

Different properties at the three vertices make a gradient, interpolated linearly across the triangle. A consumer that cannot draw gradients uses p1; one that cannot use per-triangle properties uses the object’s. Base materials cannot form gradients, so with a basematerials group p1, p2 and p3 must be equal or absent.

Triangle sets

Added in 1.3.0 in their own namespace, http://schemas.microsoft.com/3dmanufacturing/trianglesets/2021/07 (prefix t). They group triangles for editing, such as colour selections, and do not change the shape; consumers may ignore them.

Element	Attribute	Type	Use	Meaning
`t:trianglesets`	Container, inside `<mesh>` after `<triangles>`
`t:triangleset`	`name`	string	required	Readable name, not empty
	`identifier`	xs:QName	required	Identifier, unique in the mesh, not empty
`t:ref`	`index`	ST_ResourceIndex	required	One triangle index
`t:refrange`	`startindex`	ST_ResourceIndex	required	First triangle index of a range
	`endindex`	ST_ResourceIndex	required	Last triangle index, inclusive

A triangle may belong to several sets; repeated references within one set are ignored. When a disjoint split is needed, the last set containing a triangle wins.

components and component

An object made of other objects, each placed with a transform. Printers must keep the components’ relative positions, and overlapping components are united (the last one’s properties win). Fewer than 2³¹ components.

Attribute	Type	Use	Meaning
`objectid`	ST_ResourceID	required	The object to place, defined earlier
`transform`	ST_Matrix3D	optional	Placement within this object

basematerials and base

Element	Attribute	Type	Use	Meaning
`basematerials`	`id`	ST_ResourceID	required	Unique ID of the group; its `base` elements are indexed from 0
`base`	`name`	string	required	Material name expressing design intent, ideally unique and not machine-specific
	`displaycolor`	ST_ColorValue	required	Colour for showing the material on screen only; it says nothing about the printed colour

Materials apply to surfaces; the consumer decides how they fill the volume. Mapping names to real printer materials belongs to the PrintTicket. Colour for printing comes from the Materials and Properties extension. Fewer than 2³¹ materials per group.

build and item

<build> lists the items to make; nothing else is made. Items may be rearranged by the consumer to pack the build better, so interlocking parts should be made components of one object instead. Overlapping items are united, the last one’s properties winning.

Attribute	Type	Use	Meaning
`objectid`	ST_ResourceID	required	The object to make (never of type `other`)
`transform`	ST_Matrix3D	optional	Placement on the build plate, applied before making
`partnumber`	string	optional	Identifier of this item, kept if only the transform changes

Worked example

<?xml version="1.0" encoding="UTF-8"?>
<model unit="millimeter" xml:lang="en-US"
       xmlns="http://schemas.microsoft.com/3dmanufacturing/core/2015/02">
  <metadata name="Title">Tetrahedron</metadata>
  <resources>
    <basematerials id="1">
      <base name="Red PLA" displaycolor="#FF0000"/>
    </basematerials>
    <object id="2" type="model" pid="1" pindex="0">
      <mesh>
        <vertices>
          <vertex x="0" y="0" z="0"/>
          <vertex x="10" y="0" z="0"/>
          <vertex x="0" y="10" z="0"/>
          <vertex x="0" y="0" z="10"/>
        </vertices>
        <triangles>
          <triangle v1="0" v2="2" v3="1"/>
          <triangle v1="0" v2="1" v3="3"/>
          <triangle v1="0" v2="3" v3="2"/>
          <triangle v1="1" v2="2" v3="3"/>
        </triangles>
      </mesh>
    </object>
  </resources>
  <build>
    <item objectid="2" transform="1 0 0 0 1 0 0 0 1 50 50 0"/>
  </build>
</model>

A closed tetrahedron of four outward-facing triangles, in red, placed at (50, 50, 0) on the build plate.

The bottom face 0, 2, 1 has normal (0,10,0) × (10,0,0) = (0, 0, −100): pointing down, out of the solid, as required.

.3MF File Format – Core model