3MF file format: materials and properties

The Materials and Properties extension, version 1.2.1, adds colour, texture and material mixing. Its namespace is http://schemas.microsoft.com/3dmanufacturing/material/2015/02, prefix m by custom. Every new element is a resource inside <resources>; each property group has an ID, and objects and triangles select an entry with pid and pindex (or p1, p2, p3) exactly as for base materials. Each group holds fewer than 2³¹ entries, indexed from 0. Consumers that claim the extension must support all of it.

Colour spaces

Colours are #RRGGBB or #RRGGBBAA in sRGB. Vertex colours and texture samples are interpolated in sRGB. Before multiproperty blending, colours are converted to linear RGB with the standard sRGB transfer function (each channel divided by 255, then the sRGB decoding curve), blended, and converted back. Alpha is linear.

basematerials (addition)

Attribute	Type	Use	Meaning
`displaypropertiesid`	ST_ResourceID	optional	A display properties resource saying how to render the materials on screen

colorgroup and color

Element	Attribute	Type	Use	Meaning
`colorgroup`	`id`	ST_ResourceID	required	Unique resource ID
	`displaypropertiesid`	ST_ResourceID	optional	Display properties
`color`	`color`	ST_ColorValue	required	The sRGB colour, with optional alpha

Unlike a base material’s display colour, these colours are the design intent for the printed part.

texture2d

Attribute	Type	Use	Default	Meaning
`id`	ST_ResourceID	required		Unique resource ID
`path`	ST_UriReference	required		Part name of the image, which must also be the target of a 3D Texture relationship from the model part
`contenttype`	ST_ContentType	required		`image/jpeg` or `image/png`
`tilestyleu`	ST_TileStyle	optional	wrap	Behaviour outside 0–1 along u
`tilestylev`	ST_TileStyle	optional	wrap	Behaviour outside 0–1 along v
`filter`	ST_Filter	optional	auto	`auto` (best available), `linear` (bilinear) or `nearest`

Tile style	Outside 0 to 1
`wrap`	The texture repeats
`mirror`	Each repetition is reflected
`clamp`	The nearest edge pixel’s colour
`none`	The nearest edge pixel’s colour made fully transparent, so lower multiproperty layers show; as a single property or base layer it behaves as clamp

Pixel layout	Read as R, G, B, A
RGBA (PNG only)	R, G, B, A
RGB	R, G, B, FF
Grey with alpha (PNG only)	Y, Y, Y, A
Grey	Y, Y, Y, FF

Texture pixels sit at the centres of their cells. The box attribute of earlier versions was deprecated in 1.2: producers should not write it and consumers should ignore it.

texture2dgroup and tex2coord

Element	Attribute	Type	Use	Meaning
`texture2dgroup`	`id`	ST_ResourceID	required	Unique resource ID
	`texid`	ST_ResourceID	required	The `texture2d` to sample
	`displaypropertiesid`	ST_ResourceID	optional	Display properties
`tex2coord`	`u`	ST_Number	required	Horizontal coordinate, rightwards from the lower-left corner (0) to the right edge (1)
	`v`	ST_Number	required	Vertical coordinate, upwards from the bottom (0) to the top (1)

A triangle using this group with p1, p2, p3 gives each corner a texture coordinate.

compositematerials and composite

Element	Attribute	Type	Use	Meaning
`compositematerials`	`id`	ST_ResourceID	required	Unique resource ID
	`matid`	ST_ResourceID	required	The `basematerials` group the constituents come from
	`matindices`	ST_ResourceIndices	required	Space-separated indices of the constituent base materials
	`displaypropertiesid`	ST_ResourceID	optional	Display properties
`composite`	`values`	ST_Numbers	required	Space-separated proportions, 0 to 1, one per constituent

Proportions are divided by their sum; if the sum is 0, each constituent gets an equal share. Missing values count as 0; extra values are ignored. For display, the constituents’ display colours are mixed in the same proportions.

multiproperties and multi

Element	Attribute	Type	Use	Default	Meaning
`multiproperties`	`id`	ST_ResourceID	required		Unique resource ID
	`pids`	ST_ResourceIDs	required		The property groups layered, in blending order
	`blendmethods`	ST_BlendMethods	optional	mix	One of `mix` or `multiply` for each layer after the first
`multi`	`pindices`	ST_ResourceIndices	required		One index into each group of `pids`; missing ones are 0, extra ones ignored

pids may contain at most one material group (base or composite), which must come first, at most one colour group, and no other multiproperties.
Each layer is sampled and interpolated on the triangle, then blended over the accumulated result in order, in linear RGB.
mix: rgb = new.rgb × new.a + acc.rgb × (1 − new.a); a = new.a + acc.a × (1 − new.a).
multiply: rgb = new.rgb × acc.rgb; a = new.a × acc.a.
The first layer is taken as fully opaque. If it is a material, its colour may be unknown, so the consumer should skip it, start from the second layer’s RGBA, and apply the accumulated colour over the real material with an implicit mix.
There must not be more blend methods than layers minus one; missing ones are mix.

Display properties

Display properties make on-screen previews realistic (physically based rendering) and must be ignored when printing. There are five kinds. The metallic, specular and translucent kinds may be referred to only from basematerials, compositematerials and colorgroup; the two textured kinds only from texture2dgroup. Display properties never form gradients: on a triangle, p1 applies to the whole face.

Element	Attribute	Type	Use	Default	Meaning
`pbspeculardisplayproperties`	`id`	ST_ResourceID	required		Resource ID; holds `pbspecular` elements
`pbspecular`	`name`	string	required		Material name
	`specularcolor`	ST_ColorValue	optional	#383838	Specular reflectance (about 0.04 linear)
	`glossiness`	ST_Number	optional	0	Smoothness, 0 to 1
`pbmetallicdisplayproperties`	`id`	ST_ResourceID	required		Resource ID; holds `pbmetallic` elements
`pbmetallic`	`name`	string	required		Material name
	`metallicness`	ST_Number	required	0	0 dielectric to 1 pure metal
	`roughness`	ST_Number	required	1	0 to 1; 1 − roughness is glossiness
`pbspeculartexturedisplayproperties`	`id`	ST_ResourceID	required		Resource ID
	`name`	string	required		Material name
	`speculartextureid`	ST_ResourceID	required		Texture of specular colour
	`glossinesstextureid`	ST_ResourceID	required		Texture of glossiness
	`diffusefactor`	ST_ColorValue	optional	#FFFFFF	Diffuse colour multiplier
	`specularfactor`	ST_ColorValue	optional	#FFFFFF	Specular multiplier
	`glossinessfactor`	ST_Number	optional	1	Glossiness multiplier
`pbmetallictexturedisplayproperties`	`id`	ST_ResourceID	required		Resource ID
	`name`	string	required		Material name
	`metallictextureid`	ST_ResourceID	required		Texture of metallicness
	`roughnesstextureid`	ST_ResourceID	required		Texture of roughness
	`basecolorfactor`	ST_ColorValue	optional	#FFFFFF	Base colour multiplier
	`metallicfactor`	ST_Number	optional	1	Metallicness multiplier
	`roughnessfactor`	ST_Number	optional	1	Roughness multiplier
`translucentdisplayproperties`	`id`	ST_ResourceID	required		Resource ID; holds `translucent` elements
`translucent`	`name`	string	required		Material name
	`attenuation`	ST_Numbers	required		Linear attenuation coefficient per unit length, for R, G and B
	`refractiveindex`	ST_Numbers	required	1 1 1	Refractive index for R, G and B
	`roughness`	ST_Number	optional	0	Surface roughness

The specification’s appendix gives the micro-facet model (normal distribution, geometric occlusion and Fresnel terms) that viewers should use with these values.

Worked example

<model unit="millimeter" xml:lang="en-US"
  xmlns="http://schemas.microsoft.com/3dmanufacturing/core/2015/02"
  xmlns:m="http://schemas.microsoft.com/3dmanufacturing/material/2015/02">
  <resources>
    <m:colorgroup id="1">
      <m:color color="#FF0000"/>
      <m:color color="#0000FF"/>
    </m:colorgroup>
    <object id="2"  pid="1" pindex="0">
      <mesh>
        …
        <triangles>
          <triangle v1="0" v2="2" v3="1" p1="0" p2="1" p3="1"/>
          …

A colour group; the triangle fades from red at its first corner to blue at the other two.

.3MF File Format – Materials and properties