3MF Document Core Specification
Note: This report depends heavily on the official 3MF Core Specification Format found found in this link. It contains images and text from this file.
-
3MF Document. The digital manifestation of an OPC package that contains a 3D payload that conforms with the 3MF specification.
-
Editor. A software, service, or device that both reads in and writes out 3MF Documents, possibly changing the content in between.
-
The 3MF Document format represents a 3D model which represents one or more object descriptions in a markup format. It contains all the necessary information to generate a physical object through additive manufacturing or subtractive manufacturing.
-
The 3MF Document format uses a ZIP archive for its physical model.
-
The 3MF Document format includes a well defined set of parts and relationships, each fulfilling a specific purpose in the document. The format also extends the package features including digital signatures and thumbnails.
- The packaging conventions described in the Open Packaging Conventions (OPC) specification can be used to carry any payload. A payload is a complete collection of interdependent parts and relationships within a package.
- The payload in 3MF Document 3D object definition and its supporting files is called the 3D payload and it has a 3D Model root part.
It’s a payload that contains 3D Model root. There can be more than one 3D payload but there is only one primary 3D payload.
-
3MF Document StartPart relationship is a specific relationship to identify the root (3D Model part) of the 3D payload. The primary 3D payload root is the 3D Model part referenced by the 3MF Document StartPart relationship to find the primary 3D payload in the package.
-
The payload includes the full set of parts required for processing the 3D Model part and all content to be used to manufacture an object described in the #D payload must contained in the 3MF Document.
-
Parts included in the 3D payload are explicitly linked to the 3D payload root by relationship.
The parts found in 3MF Document:
A typical 3MF Document:
- The 3D model part contains definitions of one or more objects to be fabricated.
- The 3D Model part is the only valid root of a 3D payload.
- The 3D Model has 2 sections: a set of resource definitions that include objects and materials, as well as a set of specific items to actually build.
Thumbnails are small images that represent the content of the entire 3MF Document. Thumbnails part must be in JPEG or PNG format.
- It provide user intent and device configuration information to printing consumers.
- A PrintTicket can be attached only to a 3D Model part and each 3D Model part must attach no more than one PrintTicket.
- The PrintTicket format is governed by the specific consumer environment. For example, for printing on Microsoft Windows, valid PrintTicket settings are specified in the Print Schema Keywords for 3D Manufacturing specification.
- If no PrintTicket is provided or the PrintTicket provided is not supported by the consumer, it is left to the consumer to apply its own defaults.
This is the recommended convention for naming parts in the 3MF Document format:
- The 3D Model part name should contain two segments, the first being “/3D/” and the second with the extension “.model” on the last segment, For example,
“/3D/3dModel.model”. - The PrintTicket part name should be associated via a relationship with the 3D Model part and contains three segments, using “/3D/Metadata/” as the first two segments with the extension “.xml”. For example
“/3D/Metadata/Model_PT.xml”. - 3D Texture part names should contain three segments, using “/3D/Textures/” as the first two segments, for example,
“/3D/Textures/coloring.png”. 3D Texture parts must be associated with the 3D Model part via relationship. - The names of any non-standard parts that are associated with the 3D payload should contain 3 segments, using “/3D/Other/” as the first two segments.
- Coordinates are based on the right hand coordinate space. Origin is at the bottom front left corner of the device’s output field (i.e. print bed), with the x-axis increasing to the right of the output field, the y-axis increasing to the back of the output field, and the z-axis increasing to the top of the output field.
- Top —> The XY plane at the maximum printable Z value.
- Bottom —> The XY plane at the minimum (Zero) printable Z value.
- Right —> The ZY plane maximum printable X value.
- Left —> The ZY plane at the minimum (Zero) X value.
- Back —> The XY plane at the maximum printable Z value.
- Front —> The XY plane at the minimum (Zero) printable Z value.
- This matrix shouldn't be singular or nearly singular.
- The first 3 columns are only provided the fourth one has fixed values 0.0 0.0 0.0 1.0.
- The model after transformation should have a positive volume and should be located in the positive octant of the coordinate space.
- The element is the root element of the 3D Model part in the 3D payload. There exists only one model in a 3D Model part.
- A model may have 0 or many child metadata elements.
- Example in XML
<model unit=“millimeter” xml:lang=“en-US”>
<metadata name”Title”> Tree </metadata>
<resources> // A list of all resources (meshes, volumes, objects) (We’ll talk about this element later)
</resources>
<build> // A list of the objects that should actually be manufactured.
<build>
</model>
Metadata in 3MF Documents without a namespace name must be restricted to names and values defined in the specification. If the name value is not defined in the specification it must be prefixed with the namespace of an XML namespace declaration on the element. The valid names and content of metadata values include:
- Title
- Designer
- Description
- Copyright
- LicenseTerms
- Rating
- CreationData
- ModificationDate
Consumers must ignore any metadata with name they don't recognize. the content of metadata element can be any string.
A consumer that wishes to receive additional information using the previous mechanism should publish a namespace URI and a set of well-defined metadata names and expected content in order for producers to generate content in expected Format
Producers must not create multiple metadata elements with the same name.
-
element acts as the root element of a libra of constituent pieces of the overall 3D object definition (Objects, properties and materials are referred to as resources in the 3MF specification).
-
Resource IDs must be unique within the model element.
-
As we see in the resources we define element which describes an object that could be manufactured but necessarily will be manufactured. Objects are defined as resources primarily to aid in modularizing design and re-use of component, thus compacting the overall markup size.
- The build element contains one or more items (object referenced must be found in the resources element in this 3D model) to be manufactured.
- The element identifies one object resource to be output by the 3D manufacturing device. It contains the transformation matrix that must be applied to the referenced object before outputting the object.
-
Object resources describe reusable objects that may be output (by reference) or composed into more complex objects or assemblies.
-
An element has attributes for the property group and specific property member that are to be applied to the entire object except where overridden by a descendant element such as element or a component referenced element.
-
The object type is ignored in the objects that contain components as the type is always overrides by descendant objects. Producers must not assign pid or pindex attributes to objects that contain components.
-
Objects thumbnails must have and appropriate 3D Texture relationship to the model part.
- The element is the root of a triangular mesh representation of an object volume. It contains a set of vertices and a set of triangles
- The vertices element contains all elements for the current object. These vertices represent the three corners of each triangle mesh.
- A vertex array must contain less than 2^31 vertices.
- If the object type is "model", then the number of triangles must be at least 4 to form a solid body.
- A triangle element represent a single face of the mesh. The order of v1, v2 and v3 is defined in counter-clockwise order to make the face normal point outside of the object. The indices of v1, v2, v3 must be distinct.
- The property group is specified by the pid attribute, if different than the property group defined at the object level. Since this is applied to the whole triangle, it implicitly forces the three properties to be from the same group, which implies they are of the same type, as defined by possible extensions to this spec.
- The element acts as a container for all components to be composed into the current object. A component is an object resource that is used in the context of another object definition. Through the use of components, a producer can reduce the overall size of the 3MF Document. For example, if the 3MF Document describes a car 3D object, there may be a car object resource that uses 1 auto body component instance and 4 component instances of tire object resources, to place the wheels on the car’s body object after applying the necessary rotation and translation (via transform).
- A 3D manufacturing device MUST respect the relative positions of the component objects; it MUST NOT transform them relative to each other except as specified in the document.
- In order to avoid integer overflows, a components element MUST contain less than 2^31 components.
- A component selects a pre-defined object resource and adds it to the current object definition, after applying the provided matrix transform. This composition of an object definition from multiple primitive components can provide a very compact file size for a quite complex model. In keeping with the use of a simple parser, producers MUST define objects prior to referencing them as components.
I see we may ignore Thumbnails, Digital signatures, Protected content found in pages 36, 37, and 38. I see we won't need those parts when reading / writing 3MF in Slic3r.
- Material Element -> ModelMaterial.
- Triangles -> TriangleMeshes in ModelVolumes.
- Objects in Build items elements (The output) -> ModelObjects.
- base materials elements.
- Model element metadata.
- Model resources element.
- Digital signatures.
- PrintTicket.
- Thumbnail (as the file may be read from other supported formats where there are no thumbnails available).
- Should I read all objects or the ones that are considered output in the build element? I am thinking about reading all objects from 3MF file and create instances for those only are found in build element.
so I think the best logic is to do some DWIM (Do What I Mean), and assume that if there are no defined instances at all, user wants to plate things in Slic3r, so it's fine to add a default instance for each object. But if there are some instances defined it means the plate is already composed so we should only consider those
- Also there is a concern in components element in object element. How can I save those components in the ModelObject?. In other words how can I show that the components are part of the ModelObject or I should append each component object recursively to the parent object ModelVolumes.
so, regarding your second question (the one about components), we have no way to represent that an object is included in another object, and I think it's not interesting for us to expand our data structure for this until a proper usage case pops up.
In this case I think we should read the referenced objects recursively by appending their volumes to each referencing object, thus duplicating/flattening that geometry
- As we see, Materials in 3MF core specification that materials carry basic attributes (name and display color), so they describe surface of the meshes and don't say anything about the interior of the object. **textures and other advanced materials are found in the 3MF Materials and Properties Extension found here ** So, what should I do?
Back to 3MF, if you find a material attached to a triangle, that's surface information and we should ignore it. If you find it at a volume level, set the Slic3r ModelVolume to the material (direct mapping). If you find it at an object level, set it for each ModelVolume of that object
- Regarding the metadata of the model element, I am asking where to save those data in Slic3r::Model or we should ignore them if they are not saved by Slic3r.
we could just ignore them, but in order to be not too lossy :-) you could add a metadata property to the Model object
- Regarding the printTicket I don't understand how we can make use of it if applicable.
From what I understand, we can safely ignore it as it has nothing to do with Slic3r's job
- Regarding storing configuration in 3MF metadata element, How can I achieve that? as this needs to create an XML namespace as 3MF metadata name must be a one from a set of valid names.
From what you write you already have the answer.
So, when writing our 3MF files, instead of writing <metadata name="layer_height" value="0.3" /> we'll write <slic3r:metadata name="layer_height" value="0.3" />
the same when reading. You'll have to look for our <slic3r:metadata> custom tag
But you should also read/write the <metadata> tag using the approach we said before (add it to Model and other classes in Slic3r)
- Regarding part number in object element, Is this needed to be saved in Slic3r?
interesting. so they are unique identifiers we should keep attached to objects.
let's add a property to ModelObjects, and make sure you document they are used for the 3MF part numbers
I have a question here.
If I want to include Slic3r metadata what should I do here?
I must prefix the metadata name with a valid XML namespace declared on the model element. How can I achieve that?
Can I include another XML namespace specific to Slic3r and keep the same naming conventions of the specification?
I have a question here. I've found in the specification (in page 24) and I wonder if these lines will matter in reading/ writing 3MF formats in Slic3r :
If the items overlap, 3D manufacturing devices MUST use the Positive fill rule (described in section 4.1.1) to resolve the ambiguity. To avoid this, 3D manufacturing devices SHOULD NOT allow items to overlap when packing the build volume.
Answer: it's good that you pointed that out, and I can confirm Slic3r adopts the Positive fill rule. so you don't need to do anything special for that
Also I have found these lines that I didn't understand:
A 3MF Document may include multiple objects to manufacture at the same time. The arrangement of these items in the build is considered a default; consumers MAY rearrange the items for manufacturing in order to better pack the build volume. Sometimes objects are arranged in the coordinate space so as to be manufactured in an interlocking fashion; producers of these objects SHOULD collect them as components, as 3D manufacturing devices MUST NOT transform components of an object relative to each other.
Answer: the other note about objects to be manufactured at the same time means just that "an application or device reading the 3MF file can rearrange instances in the plater", which is exactly what we do :-)
Question in the annotation of "Type" attribute in the object element. Do we need to know the difference in the model type?
Please comment on this lines (I don't know if this is needed in our case or not): "Found in page 26."
Part numbers are intended as a way to keep track of objects which may have been modified during a toolchain.
When editing or processing a 3MF document, these part numbers SHOULD be preserved to the greatest degree possible, duplicating them for objects split into pieces, removing them from objects that are combined,
and maintaining them for objects that are modified.
- 3MF Materials and Properties Extension.
- 3MF Slice Extension.
- 3MF Production Extension.