From 67d1b26f6153faae6c50ebcacd0b8f223bdcc270 Mon Sep 17 00:00:00 2001 From: Jan Orend <56254096+3dJan@users.noreply.github.com> Date: Fri, 2 Aug 2024 14:46:26 +0200 Subject: [PATCH] Consistent formatting for xml tags --- 3MF Volumetric Extension Template.md | 172 ++-- 3MF Volumetric Extension.md | 1277 ++++++++++++++------------ 2 files changed, 789 insertions(+), 660 deletions(-) diff --git a/3MF Volumetric Extension Template.md b/3MF Volumetric Extension Template.md index f3b085b..52fa4c8 100644 --- a/3MF Volumetric Extension Template.md +++ b/3MF Volumetric Extension Template.md @@ -127,7 +127,7 @@ ST_ScalarID, ST_VectorID, ST_MatrixID and ST_ResourceOutputID are derived from S The format of `ST_NodeOutputIdentifier` is "nodename.outputname". The identifier must consist of alphanumeric characters and underscores. The dot (.) separates the node name and the output name. ## 2.2 ScalarReference -Element \ +Element `` ![Scalar XML Structure](images/element_scalarreference.png) | Name | Type | Use | Default | Annotation | @@ -137,7 +137,7 @@ Element \ | ref | ST_ScalarID | required | | Reference to the scalar in the form "NodeIdentifier.ScalarIdentifier". ## 2.3 VectorReference -Element \ +Element `` ![Vector XML Structure](images/element_vectorreference.png) | Name | Type | Use | Default | Annotation | @@ -147,7 +147,7 @@ Element \ | ref | ST_VectorID | required | | Reference to the scalar in the form "NodeIdentifier.VectorIdentifier". | ## 2.4 MatrixReference -Element \ +Element `` References to functions are only used for the implicit extension. @@ -159,7 +159,7 @@ References to functions are only used for the implicit extension. | ref | ST_MatrixID | required | | Reference to the scalar in the form "NodeIdentifier.VectorIdentifier". | ## 2.5 ResourceReference -Element \ +Element `` References to resources are used for the volumeData element and for the implicit extension to create a function reference. @@ -183,9 +183,9 @@ Complex Type **CT_Function** | id | ST\_ResourceID | required | | Specifies an identifier for this function resource. | | displayname | xs:string | | | Function resource name used for annotations purposes. | -Volumetric data is created with functions that are evaluatable for at given model position. Each \ element is assumed to represent a method which can be evaluated within the model being described. Functions have input arguments and output arguments, each argument MUST be one of the supported datatypes enumerated in Chapter 2. +Volumetric data is created with functions that are evaluatable for at given model position. Each `` element is assumed to represent a method which can be evaluated within the model being described. Functions have input arguments and output arguments, each argument MUST be one of the supported datatypes enumerated in Chapter 2. -\ is a container for one of three distinct function types: FunctionFromImage3d, PrivateExtensionFunction, FunctionImplicit. The only function type that MUST be supported for the volumetric extension is FunctionFromImage3D which requires an Image3d resource. +`` is a container for one of three distinct function types: FunctionFromImage3d, PrivateExtensionFunction, FunctionImplicit. The only function type that MUST be supported for the volumetric extension is FunctionFromImage3D which requires an Image3d resource. ## 3.2 FunctionFromImage3D Element **\** @@ -204,13 +204,13 @@ ISO/TC 261 | tilestylev | ST\_TileStyle | | wrap | Determines the behavior of the sampler for texture coordinate v outside the [0,1] range. | | tilestylew | ST\_TileStyle | | wrap | Determines the behavior of the sampler for texture coordinate w outside the [0,1] range. | -Elements of type \ define a function which can be sampled at any point in space from values on a voxel grid defined in the \ element. The function is evaluated by sampling the image3d at the UVW coordinates of the model position. The UVW coordinates are determined by the filter-rule and the tilestyle attributes of the \-element. +Elements of type `` define a function which can be sampled at any point in space from values on a voxel grid defined in the `` element. The function is evaluated by sampling the image3d at the UVW coordinates of the model position. The UVW coordinates are determined by the filter-rule and the tilestyle attributes of the ``-element. -To simplify parsing, producers MUST define \-elements prior to referencing them via imaged3did in a \-element. +To simplify parsing, producers MUST define ``-elements prior to referencing them via imaged3did in a ``-element. **tilestyle-u, -v or -w**: -MUST be one of "wrap", "mirror" or "clamp". This property determines the behavior of the sampler of this \ for 3d texture coordinates (u,v,w) outside the [0,1]x[0,1]x[0,1] cell. The different modes have the following interpretation (for s = u, s = v, or s = w): +MUST be one of "wrap", "mirror" or "clamp". This property determines the behavior of the sampler of this `` for 3d texture coordinates (u,v,w) outside the [0,1]x[0,1]x[0,1] cell. The different modes have the following interpretation (for s = u, s = v, or s = w): 1. "wrap" assumes periodic texture sampling, see Figure 3-1 a). A texture coordinate s that falls outside the [0,1] interval will be transformed per the following formula:
s’ = s – floor(s) @@ -221,30 +221,30 @@ MUST be one of "wrap", "mirror" or "clamp". This property determines the behavi 3. "clamp" will restrict the texture coordinate value to the [0,1] range, see Figure 3-1 c). A texture coordinate s that falls outside the [0,1] interval will be transformed according to the following formula:
s’ = min(1, max(0,s)) - _Figure 3-1: Illustration of different tilestyles. a) tilestyle wrap illustrated throughout the second \. b) tilestyle mirror illustrated throughout the second \. c) tilestyle clamp along the u-direction illustrated throughout the second \_ + _Figure 3-1: Illustration of different tilestyles. a) tilestyle wrap illustrated throughout the second ``. b) tilestyle mirror illustrated throughout the second ``. c) tilestyle clamp along the u-direction illustrated throughout the second ``_ ![Tilestyles](images/tilestyle_all.png) **filter**: -The filter attribute defines the interpolation method used when a \ is being sampled. This is illustrated in Figure 3-4. +The filter attribute defines the interpolation method used when a `` is being sampled. This is illustrated in Figure 3-4. -- If the interpolation method of an element of type \ is "nearest", sampling it at an arbitrary (u,v,w) returns the floating point value defined by the closest point (u',v',w') to (u,v,w) which transforms back to a voxel center in the 3D image resource. If a coordinate u,v, or w maps exactly at the middle between to voxel centers, sampling (u,v,w) should return the floating point value defined by the voxel center with the lower index value of the two voxel centers in question. +- If the interpolation method of an element of type `` is "nearest", sampling it at an arbitrary (u,v,w) returns the floating point value defined by the closest point (u',v',w') to (u,v,w) which transforms back to a voxel center in the 3D image resource. If a coordinate u,v, or w maps exactly at the middle between to voxel centers, sampling (u,v,w) should return the floating point value defined by the voxel center with the lower index value of the two voxel centers in question. _Figure 3-3: voxel lookup using filter method "nearest" neighbor: sampling at uvw=(1/8,2/3,0) evaluates the voxel with index-triple (0,0,0) (not (1,0,0)), and sampling at (u,v,w)=(0.5,0.5,0) evaluates the voxel with index-triple (1,1,0) (not (1,2,0))._ ![Voxel lookup using filter method "nearest" neighbor](images/lookup_filter_nearest.png) -- If the interpolation method of an element of type \ is "linear", sampling it at an arbitrary (u,v,w) returns the floating point defined by trilinearly interpolating between the eight point coordinates defining a box that contains the arbitrary (u,v,w), which transforms back to voxel centers in the 3D image resource. +- If the interpolation method of an element of type `` is "linear", sampling it at an arbitrary (u,v,w) returns the floating point defined by trilinearly interpolating between the eight point coordinates defining a box that contains the arbitrary (u,v,w), which transforms back to voxel centers in the 3D image resource. _Figure 3-4: filter attributes "nearest" (a) and "linear" (b). The greyscale channel ("Y") of the image 3d of Figure 3-1 is reused in this example. The region shown is clipped at w=0.75, v=1/6 and u=2. The grey wireframe box indicates the UVW unit box. The tilesyle is "wrap" in all directions._ ![Tilestyle mirror](images/filter.png) **`offsetvalue` and `scalevalue`**: -The values `V'` sampled from the \ are linearly scaled via `offsetvalue` and `scalevalue` giving a sampled value `V'' = V'*scalevalue + offsetvalue` +The values `V'` sampled from the `` are linearly scaled via `offsetvalue` and `scalevalue` giving a sampled value `V'' = V'*scalevalue + offsetvalue` -A \ is a container for an image3D which is evaluatable. In contrast to implict functions, the inputs and outputs of a functionfromimage3d are fixed and are not defined in the markup, but can be referenced by \ elements or as an output of a functionCall-Node in the implicit extension. +A `` is a container for an image3D which is evaluatable. In contrast to implict functions, the inputs and outputs of a functionfromimage3d are fixed and are not defined in the markup, but can be referenced by `` elements or as an output of a functionCall-Node in the implicit extension. It has the following input and outputs: **Inputs:** @@ -325,9 +325,9 @@ Element **\** | id | ST\_ResourceID | required | | Specifies an identifier for this image3d resource. | | name | xs:string | | | 3d image resource name used for annotations purposes. | -Volumetric data can be encoded as 3d images that consist of voxels. Each \ element is assumed to represent a finite voxel grid from which data can be sampled. +Volumetric data can be encoded as 3d images that consist of voxels. Each `` element is assumed to represent a finite voxel grid from which data can be sampled. -\ is a container for different representations of voxeldata. This specification defines only the \-elements. Later versions of this specification might provide alternative child elements for the \ element. +`` is a container for different representations of voxeldata. This specification defines only the ``-elements. Later versions of this specification might provide alternative child elements for the `` element. ## 4.2 ImageStack @@ -337,15 +337,15 @@ Element **\** | Name | Type | Use | Default | Annotation | | --- | --- | --- | --- | --- | -| rowcount | xs:positiveinteger | required || Number of pixel rows in all child \-elements. | -| columncount | xs:positiveinteger | required || Number of pixel columns in all child \-elements. | -| sheetcount | xs:positiveinteger | required || Number of \-elements within this \ element. | +| rowcount | xs:positiveinteger | required || Number of pixel rows in all child ``-elements. | +| columncount | xs:positiveinteger | required || Number of pixel columns in all child ``-elements. | +| sheetcount | xs:positiveinteger | required || Number of ``-elements within this `` element. | Volumetric images can be embedded inside a 3MF file using groups of PNG images that represent a stack of images. -All \-elements within an imagestack MUST have the same number of rows and columns that is specified in the rowcount and columncount-attributes, respectively. rowcount, columncount and sheetcount MUST not exceed 1024^3, each. The total number of voxels MUST be limited by 1024^5. There MUST be exactly sheetcount \-elements under \ that are implicitly ordered starting with index 0. +All ``-elements within an imagestack MUST have the same number of rows and columns that is specified in the rowcount and columncount-attributes, respectively. rowcount, columncount and sheetcount MUST not exceed 1024^3, each. The total number of voxels MUST be limited by 1024^5. There MUST be exactly sheetcount ``-elements under `` that are implicitly ordered starting with index 0. -Imagestack objects, and thus all underlying \ elements, MUST follow one of the input pixel layouts shown in the table below. All imagesheets within an imagestack MUST have the same input pixel layouts, and each channel MUST have the same bit-depth across all imagesheets. Pixel values sampled from a PNG file with a bitdepth of `N` bits will be normalized to +Imagestack objects, and thus all underlying `` elements, MUST follow one of the input pixel layouts shown in the table below. All imagesheets within an imagestack MUST have the same input pixel layouts, and each channel MUST have the same bit-depth across all imagesheets. Pixel values sampled from a PNG file with a bitdepth of `N` bits will be normalized to `pixelvalue / (2^N-1)`, i.e. a fully separated channel is normalized to 1, the minimum sampled value is normalized to 0. The following table shows the logical interpretation of sampling the "R", "G", "B" or "A"-channel depending on the input pixel layouts. The meaning of symbols is as follows: R – red, G – green, B – blue, A – alpha, Y – greyscale. @@ -357,15 +357,15 @@ The following table shows the logical interpretation of sampling the "R", "G", " | YA | Y | Y | Y | A | | Y | Y | Y | Y | 1 | -For example, if a function output from \ in a 3MF-file that maps to the R(ed) channel, but the referenced image is only monochromatic, then the greyscale channel is interpreted as the R color channel. Similarly, color values sampled from a monochromatic image are interpreted as if all "R", "G", "B" color channels share the same greyscale value. If there is no alpha channel present in the image, the highest possible value `1` MUST be used. +For example, if a function output from `` in a 3MF-file that maps to the R(ed) channel, but the referenced image is only monochromatic, then the greyscale channel is interpreted as the R color channel. Similarly, color values sampled from a monochromatic image are interpreted as if all "R", "G", "B" color channels share the same greyscale value. If there is no alpha channel present in the image, the highest possible value `1` MUST be used. -The \-element defines a voxel grid of values (e.g. RGB, grey-Alpha, grey) values distributed in a cuboid ({0,1,...,rowcount-1} x {0,1,...,columncount-1} x {0,1,...,sheetcount-1}). The left-front-bottom corner of this grid corresponds to the (0,0,0)-UVW coordinate when this 3D Image is being sampled, whereas the right-back-top corner corresponds to the (1,1,1) UVW-coordinate. Each \ corresponds to one PNG-file in the package. Figure 2-1 a) illustrates a voxel grid with `rowcount=3`, `columncount=4` and `sheetcount=2` voxels. Voxel indices are shown as bold black triple, the UVW-coordinate values as red triples. -Figure 2-1 b) illustrates the voxel indices and the UVW-values throughout the first \, Figure 2-1 c) illustrates these quantities throughout the second \. A voxel index triple `(i,j,k)` corresponds to a voxel with rowindex `i`, columnindex `j` and sheetindex `k`. +The ``-element defines a voxel grid of values (e.g. RGB, grey-Alpha, grey) values distributed in a cuboid ({0,1,...,rowcount-1} x {0,1,...,columncount-1} x {0,1,...,sheetcount-1}). The left-front-bottom corner of this grid corresponds to the (0,0,0)-UVW coordinate when this 3D Image is being sampled, whereas the right-back-top corner corresponds to the (1,1,1) UVW-coordinate. Each `` corresponds to one PNG-file in the package. Figure 2-1 a) illustrates a voxel grid with `rowcount=3`, `columncount=4` and `sheetcount=2` voxels. Voxel indices are shown as bold black triple, the UVW-coordinate values as red triples. +Figure 2-1 b) illustrates the voxel indices and the UVW-values throughout the first ``, Figure 2-1 c) illustrates these quantities throughout the second ``. A voxel index triple `(i,j,k)` corresponds to a voxel with rowindex `i`, columnindex `j` and sheetindex `k`. __Note__: The columnindex (`j`) relates to the UVW-coordinate `U`, whereas the rowindex `i` relates to the UVW-coordinate `V`. This definition is inline with the Materials and Properties specification https://github.com/3MFConsortium/spec_materials/blob/1.2.1/3MF%20Materials%20Extension.md#chapter-6-texture-2d. -The sampling rules for UVW values are determined by the filter-rule, and the behavior for UVW-values outside the unit-cube are determined by the tilestyle attributes [of the \](#32-functionfromimage3d). +The sampling rules for UVW values are determined by the filter-rule, and the behavior for UVW-values outside the unit-cube are determined by the tilestyle attributes [of the ``](#32-functionfromimage3d). _Figure 2-1: Voxel indixes and UVW-texture space of a sample voxel grid: a) shows a voxel grid of 3x4x2 voxels. b) shows a section view of the bottom voxels, c) shows a section view of the top voxels. The orange voxel at the right, front and bottom of a) has rowindex=2, columnindex=3 and sheetindex=0. d) shows the voxelcenters of this configuration._ ![Voxel indices and UVW-texture space of a sample voxel grid](images/image3dcoordinates.png) @@ -391,9 +391,9 @@ __Note__: Introductory information about the Open Packaging Conventions (OPC) ca It is RECOMMENDED that producers of 3MF Documents with the Volumetric Extension specification use the following part naming convention: -Paths of \ SHOULD consist of four segments. "/3D/volumetric/" as the first two segments, the name of a \-element that references this \ as third segment (for example "/3D/volumetric/mixingratios/", and the name of the imagesheet as last segment (for example "sheet0001.png"). Each part in the 3MF package that is referred to by the path of an \ MUST be associated with the 3D Model part via the 3D Texture relationship. +Paths of `` SHOULD consist of four segments. "/3D/volumetric/" as the first two segments, the name of a ``-element that references this `` as third segment (for example "/3D/volumetric/mixingratios/", and the name of the imagesheet as last segment (for example "sheet0001.png"). Each part in the 3MF package that is referred to by the path of an `` MUST be associated with the 3D Model part via the 3D Texture relationship. -This implies that all parts for \ in an imagestack SHOULD be located in the same OPC folder. +This implies that all parts for `` in an imagestack SHOULD be located in the same OPC folder. _Figure 2-3: OPC package layout_ ![OPC package layout](images/OPC_overview.png) @@ -408,19 +408,19 @@ Element **\** | --- | --- | --- | --- | --- | | path | ST\_UriReference | required | | Specifies the OPC part name (i.e. path) of the image data file | -Each \ element has one required attribute. The path property determines the part name (i.e. path) of the 2D image data (see chapter 6 of the Materials & Properties Extension specification for more information). +Each `` element has one required attribute. The path property determines the part name (i.e. path) of the 2D image data (see chapter 6 of the Materials & Properties Extension specification for more information). __Note__: -Other file formats like OpenVDB, OpenEXR, or VTK offer similar functionality as a stack of PNGs and are more efficient at doing so. However, their use in a manufacturing environment is hard as these formats are conceptually more complex and harder to implement. Therefore, this specification relies on the human readable and conceptually simpler stack of PNGs. Later versions of this extension, or private extension of the 3MF format MAY use different 3D image formats to encode a volumetric data as different child elements of \ and benefit from their advanced features. The remainder of this specification deals with the mapping of volumetric data onto mesh-objects in a 3MF file and giving this volumetric data a meaning for additive manufacturing processes. Adding a different data format for a voxel grid as child under \ would not affect the remaining parts of this specification. +Other file formats like OpenVDB, OpenEXR, or VTK offer similar functionality as a stack of PNGs and are more efficient at doing so. However, their use in a manufacturing environment is hard as these formats are conceptually more complex and harder to implement. Therefore, this specification relies on the human readable and conceptually simpler stack of PNGs. Later versions of this extension, or private extension of the 3MF format MAY use different 3D image formats to encode a volumetric data as different child elements of `` and benefit from their advanced features. The remainder of this specification deals with the mapping of volumetric data onto mesh-objects in a 3MF file and giving this volumetric data a meaning for additive manufacturing processes. Adding a different data format for a voxel grid as child under `` would not affect the remaining parts of this specification. # Chapter 5 LevelSet ### 5.1.1 LevelSet element A powerful application of Volumetric and Implicit modeling is the ability to define the shape of an object from volumetric information. Therefore we are introducing the concept of a **\** element which can be used to define the boundary of a shape using a levelset function. This is analogous to how a mesh defines the boundary between the inside and outside of the shape. In this case the mesh surface represents the surface of the levelset value equal to zero. -The child-element of the \-element references a functionID that must have a scalar output. This 'shape' represents the levelset function that MUST be evaluated to determine the actual shape of the object. +The child-element of the ``-element references a functionID that must have a scalar output. This 'shape' represents the levelset function that MUST be evaluated to determine the actual shape of the object. -Since fields can be evaluated in an unbounded way, a closed mesh is required to enclose any levelset element to make the evaluation space bounded. For example a simple box that represents the bounding box of the geometry encoded in the \-element. There are cases where a producer would want to specify a bounding box for evaluation. In that case one can set the the \-element to true and the \-element must be evaluated within the extents of the mesh referenced by the \-element. +Since fields can be evaluated in an unbounded way, a closed mesh is required to enclose any levelset element to make the evaluation space bounded. For example a simple box that represents the bounding box of the geometry encoded in the ``-element. There are cases where a producer would want to specify a bounding box for evaluation. In that case one can set the the ``-element to true and the ``-element must be evaluated within the extents of the mesh referenced by the ``-element. Element **\** @@ -428,25 +428,25 @@ Element **\** | Name | Type | Use | Default | Annotation | | -------------- | ------------ | -------- | ------- | -------------------------------------------------------------------- | -| functionid | ST_ResourceID| required | | ResourceID of the \ that provides the boundary as a level set. | +| functionid | ST_ResourceID| required | | ResourceID of the `` that provides the boundary as a level set. | | channel | xs:QName | required | | Name of the output of the function to be used for the levelset. The output must be a scalar | -| transform | ST_Matrix3D | | Identity | Transformation of the object coordinate system into the \ coordinate system. | +| transform | ST_Matrix3D | | Identity | Transformation of the object coordinate system into the `` coordinate system. | | minfeaturesize | ST_Number | | 0.0 | Specifies the minimum size of features to be considered in the boundary. | -| meshid | ST_ResourceID| required | | ResourceID of the \ that is used to define the evaluation domain of the level set.| +| meshid | ST_ResourceID| required | | ResourceID of the `` that is used to define the evaluation domain of the level set.| | meshbboxonly | xs:boolean | | false | Indicates whether to consider only the bounding box of the mesh for the level set. | | fallbackvalue | ST_Number | | 0.0 | Specifies the value to be used for this data element if the output of the referenced function is undefined | -| volumeid | ST_ResourceID | | | ResourceID of a \-Resource to apply on the object | +| volumeid | ST_ResourceID | | | ResourceID of a ``-Resource to apply on the object | -The \-element is used to describe the interior and exterior of an object via a levelset function. +The ``-element is used to describe the interior and exterior of an object via a levelset function. If meshbboxonly is set to true, the boundary is only intersected with the bounding box of the mesh. This allows the consumer to evaluate the boundary without computing the intersection with the mesh, otherwise the boundary is intersected with the mesh. -To simplify parsing, producers MUST define a \>-element prior to referencing it via the functionid-attribute in a \-element. +To simplify parsing, producers MUST define a ``>-element prior to referencing it via the functionid-attribute in a ``-element. **functionid**: -ResourceID of the \ that provides the boundary as a levelset. The function MUST have an input of type vector with the name "pos" and an output of type scalar that matches the name given as the channel attribute of the \ element. +ResourceID of the `` that provides the boundary as a levelset. The function MUST have an input of type vector with the name "pos" and an output of type scalar that matches the name given as the channel attribute of the `` element. **channel**: Defines which function output channel is used as the levelset function. The channel MUST be of type scalar. @@ -472,8 +472,8 @@ Any undefined result MUST be evaluated as the value provided. **VolumeDetermination** -_Figure 5-1: a) LevelSet A with a Mesh clipping surface. b) Mesh object B (rectangle) with \ child element Y. The mesh objects are defined in the order A-B. c) shows the volume defined by the overlapped mesh objects. d) shows \ child element X in object A, and \ child element Y in object B. The table lays out how these \ child elements are sampled at positions p1 to p4._ -![Illustration of overlapping meshes with \ child elements](images/overlap_properties.png) +_Figure 5-1: a) LevelSet A with a Mesh clipping surface. b) Mesh object B (rectangle) with `` child element Y. The mesh objects are defined in the order A-B. c) shows the volume defined by the overlapped mesh objects. d) shows `` child element X in object A, and `` child element Y in object B. The table lays out how these `` child elements are sampled at positions p1 to p4._ +![Illustration of overlapping meshes with `` child elements](images/overlap_properties.png) # Chapter 6. Volumetric Data @@ -484,7 +484,7 @@ Element **\** ![mesh XML structure](images/element_mesh.png) -The volumetric data \ element is a new OPTIONAL element which extends is a type of resource to be used by a Shape (i.e. the \ element). +The volumetric data `` element is a new OPTIONAL element which extends is a type of resource to be used by a Shape (i.e. the `` element). ## 6.2. Volumetric Data @@ -493,18 +493,18 @@ Element **\** ![volumedata XML structure](images/element_volumedata.png) -The \ defines the volumetric properties in the interior of a \ element. +The `` defines the volumetric properties in the interior of a `` element. -The child-element of the \ element reference a function, that has to match the signature requirements of the child element. -Volumedata MUST only be referenced by an object type "mesh" or "levelset" unless explicitly allowed by shapes defined in other extensions. This ensures that the \ applies to a volume. +The child-element of the `` element reference a function, that has to match the signature requirements of the child element. +Volumedata MUST only be referenced by an object type "mesh" or "levelset" unless explicitly allowed by shapes defined in other extensions. This ensures that the `` applies to a volume. Moreover, the volumedata-element MUST not be used in a mesh that is referenced as "originalmesh" by any other mesh. This excludes the possibility to implicitly mirror volumedata, which makes it easier to consume files with this extension. -The \ element can contain up to one \ child element, up to one \ element, and up to 2^31-1 of \ elements. +The `` element can contain up to one `` child element, up to one `` element, and up to 2^31-1 of `` elements. -The child elements modify the enclosing \ by specifying color, material composition and other arbitrary properties of the \ object. +The child elements modify the enclosing `` by specifying color, material composition and other arbitrary properties of the `` object. -To rationalize how this specification modifies the definition of geometry within a 3MF model, the concept of a "clipping surface" of a mesh with a \ element is introduced. -The clipping surface is defined by the surface of the enclosing \ element. This implicitly takes into account any geometry defined by e.g. the beamlattices specification. +To rationalize how this specification modifies the definition of geometry within a 3MF model, the concept of a "clipping surface" of a mesh with a `` element is introduced. +The clipping surface is defined by the surface of the enclosing `` element. This implicitly takes into account any geometry defined by e.g. the beamlattices specification. This clipping surface trims any volumetric data defined therein. Any data outside the clipping surface MUST be ignored. The geometry that should be printed is defined by the interior of the clipping surface. @@ -520,11 +520,11 @@ Defining conflicting surface- and volumetric properties can be very powerful, e. The properties at surface regions that are not explicitly specified are instead given by the volumetric properties. Conflicting properties must be handled as follows: -1. Producers MUST not define colors, materials or properties via child elements of the \ element that are impossible on physical grounds (e.g. non-conducting copper). +1. Producers MUST not define colors, materials or properties via child elements of the `` element that are impossible on physical grounds (e.g. non-conducting copper). 2. Consumers that read files with properties that cannot be realized due to limitations specific to them (e.g. a specific manufacturing device that does not support a material in a specific color), SHOULD raise a warning, but MAY handle this in any appropriate way for them. If there is an established process between Producer and Consumer, resolution of such conflicts SHOULD be performed e.g. via negotiation through printer capabilities and a print ticket. -__Note__: In the case where objects with different \ child elements overlap, only the \ child elements from last object can be used. -This makes sure that \ child elements of an overlapped object do not determine the value of any \ child elements of an overlapping object. Figure 5-1 illustrates this behavior. +__Note__: In the case where objects with different `` child elements overlap, only the `` child elements from last object can be used. +This makes sure that `` child elements of an overlapped object do not determine the value of any `` child elements of an overlapping object. Figure 5-1 illustrates this behavior. ### 6.2.1 Color element @@ -535,14 +535,14 @@ Element **\** | Name | Type | Use | Default | Annotation | | --------------- | -------------- | -------- | ------- | --------------------------------------------------------- | || functionid | ST_ResourceID | required | | Model Resource Id of the function providing the color | -| transform | ST_Matrix3D | | | Transformation of the object coordinate system into the \ coordinate system. | +| transform | ST_Matrix3D | | | Transformation of the object coordinate system into the `` coordinate system. | | channel | xs:QName | required | | Name of the function ouput to be used as color. The output must be of type vector | | minfeaturesize | ST_Number | | 0.0 | Hint for the minimum size of features. | | fallbackvalue | ST_Number | | 0.0 | Specifies the value to be used for this data element if the output of the referenced function is undefined | -To simplify parsing, producers MUST define a \-element prior to referencing it via the vector3dfieldid in a \-element. +To simplify parsing, producers MUST define a ``-element prior to referencing it via the vector3dfieldid in a ``-element. -The \ element is used to define the color of the object. +The `` element is used to define the color of the object. The color MUST be interpreted in linearized sRGB color space as defined in the Materials and Properties specification https://github.com/3MFConsortium/spec_materials/blob/1.2.1/3MF%20Materials%20Extension.md#12-srgb-and-linear-color-values. The vector components `x`, `y` and `z` of the 3D vector field are interpreted as the "R", "G" and "B" channels of the color of the enclosing meshobject, respectively. If either channel evaluates to a value \<0 or \>1 it has to be truncated at 0 or 1, respectively. @@ -552,7 +552,7 @@ This specification does not capture well the properties for semi-transparent, di **transform**: The transformation of the object coordinate system into the coordinate system of the function (e.g. noramlized coordinates for functionFromImage3D). -If this \>-element is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the 3D vector field must be sampled at position `(x',y',z') = T*(x,y,z)`. +If this ``>-element is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the 3D vector field must be sampled at position `(x',y',z') = T*(x,y,z)`. **channel** @@ -574,22 +574,22 @@ Element **\** | Name | Type | Use | Default | Annotation | | --- | --- | --- | --- | --- | -| basematerialid | ST\_ResourceID | required | | ResourceID of the \ element that holds the \-elements referenced in the child \-elements. | +| basematerialid | ST\_ResourceID | required | | ResourceID of the `` element that holds the ``-elements referenced in the child ``-elements. | -The \ element describes a mixing ratio of printer materials at each position in space. The CONSUMER can determine the halftoning, mixing or dithering strategy that can be used to achieve these mixtures. +The `` element describes a mixing ratio of printer materials at each position in space. The CONSUMER can determine the halftoning, mixing or dithering strategy that can be used to achieve these mixtures. -This element MUST contain at least one \ element, which will encode the relative contribution of a specific basematerial to the material mix. +This element MUST contain at least one `` element, which will encode the relative contribution of a specific basematerial to the material mix. -The number of \-elements in the \ element referenced by a \ element MUST equal the number of \-elements in the \ element. To simplify parsing, producers MUST define the referenced \-element prior to referencing it via the basematerialid in a \-element. +The number of ``-elements in the `` element referenced by a `` element MUST equal the number of ``-elements in the `` element. To simplify parsing, producers MUST define the referenced ``-element prior to referencing it via the basematerialid in a ``-element. -Producers MUST NOT create files where the sum of all values in its child \-elements is smaller than `10^-5`. If the total is smaller than this threshold, the mixing ratio is up to the consumer. +Producers MUST NOT create files where the sum of all values in its child ``-elements is smaller than `10^-5`. If the total is smaller than this threshold, the mixing ratio is up to the consumer. - If there are `N` materials, then the mixing ration of material `i` at point `X` is given by: ``` value of channel i / sum(value of all N mixing contributions at point X) ``` -The order of the -elements defines an implicit 0-based index. This index corresponds to the index defined by the \- elements in the \-element of the core specification. +The order of the -elements defines an implicit 0-based index. This index corresponds to the index defined by the ``- elements in the ``-element of the core specification. ## 6.2.3 Material mapping element @@ -599,20 +599,20 @@ Element **\** | Name | Type | Use | Default | Annotation | | -------------- | ------------- | -------- | ------- | --------------------------------------------------------- | -| functionid | ST_ResourceID | required | | ResourceID of the \ providing the mixing contribution value for a material in the \-element. | -| transform | ST_Matrix3D | | | Transformation of the object coordinate system into the \ coordinate system | +| functionid | ST_ResourceID | required | | ResourceID of the `` providing the mixing contribution value for a material in the ``-element. | +| transform | ST_Matrix3D | | | Transformation of the object coordinate system into the `` coordinate system | | channel | xs:QName | required | | Name of the function output to be used for the mixing contribution. The output must be a scalar. | | minfeaturesize | ST_Number | | 0 | Hint for the minimum size of features. | | fallbackvalue | ST_Number | | 0.0 | Specifies the value to be used for this data element if the output of the referenced function is undefined | -The \ element defines the relative contribution of a specific material to the mixing of materials in it's parent \-element. +The `` element defines the relative contribution of a specific material to the mixing of materials in it's parent ``-element. -To simplify parsing, producers MUST define the referenced \-element prior to referencing it via the functionid in a \-element. +To simplify parsing, producers MUST define the referenced ``-element prior to referencing it via the functionid in a ``-element. **transform**: The transformation of the object coordinate system into the scalar field coordinate system. -If any channel of a \ is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the referenced scalar field must be sampled at position `(x',y',z') = T*(x,y,z)`. +If any channel of a `` is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the referenced scalar field must be sampled at position `(x',y',z') = T*(x,y,z)`. **channel**: @@ -626,7 +626,7 @@ The minimum size of features to be considered in the mixing contribution. This i If this attribute is set, any undefined result MUST be evaluated as the value. -If the sampled value of a \ is `<0` it must be evaluated as "0". +If the sampled value of a `` is `<0` it must be evaluated as "0". ### 6.2.4 Property element @@ -636,21 +636,21 @@ Element **\** | Name | Type | Use | Default | Annotation | | --- | --- | --- | --- | --- | -| functionid | ST\_ResourceID | required | | ResourceID of the \ that provides the value of this property | -| transform | ST\_Matrix3D | | | Transformation of the object coordinate system into the \ coordinate system | +| functionid | ST\_ResourceID | required | | ResourceID of the `` that provides the value of this property | +| transform | ST\_Matrix3D | | | Transformation of the object coordinate system into the `` coordinate system | | channel | xs:QName | required | | Name of the function output to be used for the property. | -| name | xs:QName | required | | Contains either the name of the property, defined in a 3MF extension specification, or the name of a vendor-defined property. Either MUST be prefixed with a valid XML namespace name declared on the \ element. | +| name | xs:QName | required | | Contains either the name of the property, defined in a 3MF extension specification, or the name of a vendor-defined property. Either MUST be prefixed with a valid XML namespace name declared on the `` element. | | required | xs:boolean | | false | Indicator whether this property is required to process this 3MF document instance. | | fallbackvalue | ST_Number | | 0.0 | Specifies the value to be used for this data element if the output of the referenced function is undefined | -The \ element allows to assign any point in space a scalar or vectorial value of a freely definable property. This can be used to assign, e.g. opacity, conductivity, or translucency. +The `` element allows to assign any point in space a scalar or vectorial value of a freely definable property. This can be used to assign, e.g. opacity, conductivity, or translucency. -To simplify parsing, producers MUST define the referenced \-element prior to referencing it via the functionid in a \-element. +To simplify parsing, producers MUST define the referenced ``-element prior to referencing it via the functionid in a ``-element. **transform**: -The transformation of the object coordinate system into the \ coordinate system. -If a \-element is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the referenced \ must be sampled at position `(x',y',z') = T*(x,y,z)`. +The transformation of the object coordinate system into the `` coordinate system. +If a ``-element is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the referenced `` must be sampled at position `(x',y',z') = T*(x,y,z)`. **channel**: @@ -660,19 +660,19 @@ This specification does not provide qualified names for such properties as part A later extension of the 3MF format might define such qualified names as part of a different extension specification or a later version of the volumetric extension specification. Producers that want to specify such properties now, SHOULD define a qualified name that can e.g. be called "http://www.vendorwwebsite.com/3mf/vendor13mfextension/2021/05". The specifications of private namespaces (that are not ratified by the 3MF Consortium) MUST be negotiated between producer and consumer of a 3MF file. -The names of \-elements MUST be unique within a \. This name MUST be prefixed with a valid XML namespace name declared on the element. +The names of ``-elements MUST be unique within a ``. This name MUST be prefixed with a valid XML namespace name declared on the element. The interpretation of the value MUST be defined by the owner of the namespace. __Note__: -The producer of a 3MF file is responsible for assembling the values in the \ (and the referenced \ such that sampling it in the print-bed coordinate system as a e.g. physical property, is sensible. This requirement is particularly important if the accumulated transformation `T0` between print-bed coordinates and local object coordinates is not a rigid body transformation. +The producer of a 3MF file is responsible for assembling the values in the `` (and the referenced `` such that sampling it in the print-bed coordinate system as a e.g. physical property, is sensible. This requirement is particularly important if the accumulated transformation `T0` between print-bed coordinates and local object coordinates is not a rigid body transformation. (The transformation `T0` of the print-bed coordinate system into the object coordinate system is given by the `transform`-attributes on the `item` and `component`-elements in the path that leads to this object in the `build`-hierarchy of the 3MF Core Specification (see https://github.com/3MFConsortium/spec_core/blob/1.3.0/3MF%20Core%20Specification.md#3431-item-element and https://github.com/3MFConsortium/spec_core/blob/1.3.0/3MF%20Core%20Specification.md#421-component, and Figure 6.2 in this document). If the interpretation of a property might result in a conflict with the standard volumedata-elements (boundary, color, composite) the namespace-owner MUST specify a resolution to the conflict. A producer MUST NOT create files with properties that conflict with each other. If a physical unit is necessary, the namespace owner MUST define a unique and unambiguous physical unit system for the namespace. The unit system SHOULD be metric. -If a \ is marked as `required`, and a consumer does not support it, it MUST warn the user or the appropriate upstream processes that it cannot process all contents in this 3MF document instance. -Producers of 3MF files MUST mark all volumetric \-elements required to represent the design intent of a model as `required`. +If a `` is marked as `required`, and a consumer does not support it, it MUST warn the user or the appropriate upstream processes that it cannot process all contents in this 3MF document instance. +Producers of 3MF files MUST mark all volumetric ``-elements required to represent the design intent of a model as `required`. # Chapter 7. Notes @@ -686,20 +686,20 @@ It is RECOMMENDED that calculations during evaluation of the graph are performed Equipped with the language elements of this specification, one can recapitulate the core concepts with an overview of the sampling process. -Figure 7-1 illustrates the 3MF elements, the different coordinate systems and transforms between them when a \ element (in this case \) is sampled in the object coordinate space. +Figure 7-1 illustrates the 3MF elements, the different coordinate systems and transforms between them when a `` element (in this case ``) is sampled in the object coordinate space. Figure 7-1 a) The object's color is sampled at position (+) in the print-bed coordinate system. The clipping surface is hinted at with a wireframe. The transformation `T0` of the print-bed coordinate system into the object coordinate system is given by the `transform`-attributes on the `item` and `component`-elements in the path that leads to this object in the `build`-hierarchy of the 3MF Core Specification (see https://github.com/3MFConsortium/spec_core/blob/1.3.0/3MF%20Core%20Specification.md#3431-item-element and https://github.com/3MFConsortium/spec_core/blob/1.3.0/3MF%20Core%20Specification.md#421-component). -Figure 7-1 b) shows the \ underlying the color of the object. The sampling point is represented in the coordinate system of the \. The transformation `T1` from object coordinate space to \ coordinate system is given by the `transform`-element in the \-element. The original clipping surface from a) is only shown for illustration porpuses. It does not exist in the \ context. -The color value sampled in this illustration directly originates from a \ element. +Figure 7-1 b) shows the `` underlying the color of the object. The sampling point is represented in the coordinate system of the ``. The transformation `T1` from object coordinate space to `` coordinate system is given by the `transform`-element in the ``-element. The original clipping surface from a) is only shown for illustration porpuses. It does not exist in the `` context. +The color value sampled in this illustration directly originates from a `` element. -Figure 7-1 c) Shows the \ again. The unit box of the UVW coordinate system is shown as a wireframe. The transformation `T2` between \ coordinate system and UVW space is given according to the `transform`-attribute of the \ element. +Figure 7-1 c) Shows the `` again. The unit box of the UVW coordinate system is shown as a wireframe. The transformation `T2` between `` coordinate system and UVW space is given according to the `transform`-attribute of the `` element. -Figure 7-1 d) Shows the UVW coordinate space of the \-element and where the sampling point (+) is evaluated, and the UVW-locations to which the voxel centers of the underlying \-element map. +Figure 7-1 d) Shows the UVW coordinate space of the ``-element and where the sampling point (+) is evaluated, and the UVW-locations to which the voxel centers of the underlying ``-element map. -Figure 7-1 e) illustrates where the sampling point (+) ends up in the voxel index space of the \. The mapping of UVW to voxel indices in the \-element is described in [Chapter 2. 3D Image](#chapter-2-3d-image). +Figure 7-1 e) illustrates where the sampling point (+) ends up in the voxel index space of the ``. The mapping of UVW to voxel indices in the ``-element is described in [Chapter 2. 3D Image](#chapter-2-3d-image). -_Figure 7-1: Illustration of the different coordinate systems and 3MF elements in the sampling process. a) the object to be sampled at position (+). b) A view into the \. The original clipping surface from a) is only shown for illustration porpuses. c) Shows the \ again. The unit box of the UVW coordinate system is shown as a wireframe. d) The UVW coordinate space and the UVW-locations to which the voxel-centers map. e) The sampling point (+) in the voxel index space._ +_Figure 7-1: Illustration of the different coordinate systems and 3MF elements in the sampling process. a) the object to be sampled at position (+). b) A view into the ``. The original clipping surface from a) is only shown for illustration porpuses. c) Shows the `` again. The unit box of the UVW coordinate system is shown as a wireframe. d) The UVW coordinate space and the UVW-locations to which the voxel-centers map. e) The sampling point (+) in the voxel index space._ ![Illustration of different coordinate systems in the sampling process](images/fig_coordinatesystems.png) ## 7.3. Limitations diff --git a/3MF Volumetric Extension.md b/3MF Volumetric Extension.md index da61c90..c94a575 100644 --- a/3MF Volumetric Extension.md +++ b/3MF Volumetric Extension.md @@ -127,7 +127,7 @@ ST_ScalarID, ST_VectorID, ST_MatrixID and ST_ResourceOutputID are derived from S The format of `ST_NodeOutputIdentifier` is "nodename.outputname". The identifier must consist of alphanumeric characters and underscores. The dot (.) separates the node name and the output name. ## 2.2 ScalarReference -Element \ +Element `` ![Scalar XML Structure](images/element_scalarreference.png) | Name | Type | Use | Default | Annotation | @@ -137,7 +137,7 @@ Element \ | ref | ST_ScalarID | required | | Reference to the scalar in the form "NodeIdentifier.ScalarIdentifier". ## 2.3 VectorReference -Element \ +Element `` ![Vector XML Structure](images/element_vectorreference.png) | Name | Type | Use | Default | Annotation | @@ -147,7 +147,7 @@ Element \ | ref | ST_VectorID | required | | Reference to the scalar in the form "NodeIdentifier.VectorIdentifier". | ## 2.4 MatrixReference -Element \ +Element `` References to functions are only used for the implicit extension. @@ -159,7 +159,7 @@ References to functions are only used for the implicit extension. | ref | ST_MatrixID | required | | Reference to the scalar in the form "NodeIdentifier.VectorIdentifier". | ## 2.5 ResourceReference -Element \ +Element `` References to resources are used for the volumeData element and for the implicit extension to create a function reference. @@ -183,9 +183,9 @@ Complex Type **CT_Function** | id | ST\_ResourceID | required | | Specifies an identifier for this function resource. | | displayname | xs:string | | | Function resource name used for annotations purposes. | -Volumetric data is created with functions that are evaluatable for at given model position. Each \ element is assumed to represent a method which can be evaluated within the model being described. Functions have input arguments and output arguments, each argument MUST be one of the supported datatypes enumerated in Chapter 2. +Volumetric data is created with functions that are evaluatable for at given model position. Each `` element is assumed to represent a method which can be evaluated within the model being described. Functions have input arguments and output arguments, each argument MUST be one of the supported datatypes enumerated in Chapter 2. -\ is a container for one of three distinct function types: FunctionFromImage3d, PrivateExtensionFunction, FunctionImplicit. The only function type that MUST be supported for the volumetric extension is FunctionFromImage3D which requires an Image3d resource. +`` is a container for one of three distinct function types: FunctionFromImage3d, PrivateExtensionFunction, FunctionImplicit. The only function type that MUST be supported for the volumetric extension is FunctionFromImage3D which requires an Image3d resource. ## 3.2 FunctionFromImage3D Element **\** @@ -204,13 +204,13 @@ ISO/TC 261 | tilestylev | ST\_TileStyle | | wrap | Determines the behavior of the sampler for texture coordinate v outside the [0,1] range. | | tilestylew | ST\_TileStyle | | wrap | Determines the behavior of the sampler for texture coordinate w outside the [0,1] range. | -Elements of type \ define a function which can be sampled at any point in space from values on a voxel grid defined in the \ element. The function is evaluated by sampling the image3d at the UVW coordinates of the model position. The UVW coordinates are determined by the filter-rule and the tilestyle attributes of the \-element. +Elements of type `` define a function which can be sampled at any point in space from values on a voxel grid defined in the `` element. The function is evaluated by sampling the image3d at the UVW coordinates of the model position. The UVW coordinates are determined by the filter-rule and the tilestyle attributes of the ``-element. -To simplify parsing, producers MUST define \-elements prior to referencing them via imaged3did in a \-element. +To simplify parsing, producers MUST define ``-elements prior to referencing them via imaged3did in a ``-element. **tilestyle-u, -v or -w**: -MUST be one of "wrap", "mirror" or "clamp". This property determines the behavior of the sampler of this \ for 3d texture coordinates (u,v,w) outside the [0,1]x[0,1]x[0,1] cell. The different modes have the following interpretation (for s = u, s = v, or s = w): +MUST be one of "wrap", "mirror" or "clamp". This property determines the behavior of the sampler of this `` for 3d texture coordinates (u,v,w) outside the [0,1]x[0,1]x[0,1] cell. The different modes have the following interpretation (for s = u, s = v, or s = w): 1. "wrap" assumes periodic texture sampling, see Figure 3-1 a). A texture coordinate s that falls outside the [0,1] interval will be transformed per the following formula:
s’ = s – floor(s) @@ -221,30 +221,30 @@ MUST be one of "wrap", "mirror" or "clamp". This property determines the behavi 3. "clamp" will restrict the texture coordinate value to the [0,1] range, see Figure 3-1 c). A texture coordinate s that falls outside the [0,1] interval will be transformed according to the following formula:
s’ = min(1, max(0,s)) - _Figure 3-1: Illustration of different tilestyles. a) tilestyle wrap illustrated throughout the second \. b) tilestyle mirror illustrated throughout the second \. c) tilestyle clamp along the u-direction illustrated throughout the second \_ + _Figure 3-1: Illustration of different tilestyles. a) tilestyle wrap illustrated throughout the second ``. b) tilestyle mirror illustrated throughout the second ``. c) tilestyle clamp along the u-direction illustrated throughout the second ``_ ![Tilestyles](images/tilestyle_all.png) **filter**: -The filter attribute defines the interpolation method used when a \ is being sampled. This is illustrated in Figure 3-4. +The filter attribute defines the interpolation method used when a `` is being sampled. This is illustrated in Figure 3-4. -- If the interpolation method of an elements of type \ is "nearest", sampling it at an arbitrary (u,v,w) returns the floating point value defined by the closest point (u',v',w') to (u,v,w) which transforms back to a voxel center in the 3D image resource. If a coordinate u,v, or w maps exactly at the middle between to voxel centers, sampling (u,v,w) should return the floating point value defined by the voxel center with the lower index value of the two voxel centers in question. +- If the interpolation method of an element of type `` is "nearest", sampling it at an arbitrary (u,v,w) returns the floating point value defined by the closest point (u',v',w') to (u,v,w) which transforms back to a voxel center in the 3D image resource. If a coordinate u,v, or w maps exactly at the middle between to voxel centers, sampling (u,v,w) should return the floating point value defined by the voxel center with the lower index value of the two voxel centers in question. _Figure 3-3: voxel lookup using filter method "nearest" neighbor: sampling at uvw=(1/8,2/3,0) evaluates the voxel with index-triple (0,0,0) (not (1,0,0)), and sampling at (u,v,w)=(0.5,0.5,0) evaluates the voxel with index-triple (1,1,0) (not (1,2,0))._ ![Voxel lookup using filter method "nearest" neighbor](images/lookup_filter_nearest.png) -- If the interpolation method of an elements of type \ is "linear", sampling it at an arbitrary (u,v,w) returns the floating point defined by trilinearly interpolating between the eight point coordinates defining a box that contains the arbitrary (u,v,w), which transforms back to voxel centers in the 3D image resource. +- If the interpolation method of an element of type `` is "linear", sampling it at an arbitrary (u,v,w) returns the floating point defined by trilinearly interpolating between the eight point coordinates defining a box that contains the arbitrary (u,v,w), which transforms back to voxel centers in the 3D image resource. -_Figure 3-4: filter attributes "nearest" (a) and "linear" (b). The consider that the greyscale channel ("Y") of the image 3d of Figure 2-1 is reused in this example. The region shown is clipped at w=0.75, v=1/6 and u=2. The grey wireframe box indicates the UVW unit box. The tilesyle is "wrap" in all directions._ +_Figure 3-4: filter attributes "nearest" (a) and "linear" (b). The greyscale channel ("Y") of the image 3d of Figure 3-1 is reused in this example. The region shown is clipped at w=0.75, v=1/6 and u=2. The grey wireframe box indicates the UVW unit box. The tilesyle is "wrap" in all directions._ ![Tilestyle mirror](images/filter.png) **`offsetvalue` and `scalevalue`**: -The values `V'` sampled from the \ are linearly scaled via `offsetvalue` and `scalevalue` giving a sampled value `V'' = V'*scalevalue + offsetvalue` +The values `V'` sampled from the `` are linearly scaled via `offsetvalue` and `scalevalue` giving a sampled value `V'' = V'*scalevalue + offsetvalue` -A \ is a container for an image3D which is evaluatable. In contrast to implict functions, the inputs and outputs of a functionfromimage3d are fixed and are not defined in the markup, but can be referenced by volumedata elements or as an output of a functionCall-Node in the implicit extension. +A `` is a container for an image3D which is evaluatable. In contrast to implict functions, the inputs and outputs of a functionfromimage3d are fixed and are not defined in the markup, but can be referenced by `` elements or as an output of a functionCall-Node in the implicit extension. It has the following input and outputs: **Inputs:** @@ -264,7 +264,8 @@ It has the following input and outputs: The appearance of color and red, green, blue might seem redundant, but allows to also use the output directly as a vectorial field. **Example Usage:** -```xml +```xml + @@ -284,6 +285,7 @@ The appearance of color and red, green, blue might seem redundant, but allows to + ``` ## 3.3 PrivateExtensionFunction @@ -323,9 +325,9 @@ Element **\** | id | ST\_ResourceID | required | | Specifies an identifier for this image3d resource. | | name | xs:string | | | 3d image resource name used for annotations purposes. | -Volumetric data can be encoded as 3d images that consist of voxels. Each \ element is assumed to represent a finite voxel grid from which data can be sampled. +Volumetric data can be encoded as 3d images that consist of voxels. Each `` element is assumed to represent a finite voxel grid from which data can be sampled. -\ is a container for different representations of voxeldata. This specification defines only the \-elements. Later versions of this specification might provide alternative child elements for the \ element. +`` is a container for different representations of voxeldata. This specification defines only the ``-elements. Later versions of this specification might provide alternative child elements for the `` element. ## 4.2 ImageStack @@ -335,15 +337,15 @@ Element **\** | Name | Type | Use | Default | Annotation | | --- | --- | --- | --- | --- | -| rowcount | xs:positiveinteger | required || Number of pixel rows in all child \-elements. | -| columncount | xs:positiveinteger | required || Number of pixel columns in all child \-elements. | -| sheetcount | xs:positiveinteger | required || Number of \-elements within this \ element. | +| rowcount | xs:positiveinteger | required || Number of pixel rows in all child ``-elements. | +| columncount | xs:positiveinteger | required || Number of pixel columns in all child ``-elements. | +| sheetcount | xs:positiveinteger | required || Number of ``-elements within this `` element. | Volumetric images can be embedded inside a 3MF file using groups of PNG images that represent a stack of images. -All \-elements within an imagestack MUST have the same number of rows and columns that is specified in the rowcount and columncount-attributes, respectively. rowcount, columncount and sheetcount MUST not exceed 1024^3, each. The total number of voxels MUST be limited by 1024^5. There MUST be exactly sheetcount \-elements under \ that are implicitly ordered starting with index 0. +All ``-elements within an imagestack MUST have the same number of rows and columns that is specified in the rowcount and columncount-attributes, respectively. rowcount, columncount and sheetcount MUST not exceed 1024^3, each. The total number of voxels MUST be limited by 1024^5. There MUST be exactly sheetcount ``-elements under `` that are implicitly ordered starting with index 0. -Imagestack objects, and thus all underlying \ elements, MUST follow one of the input pixel layouts shown in the table below. All imagesheets within an imagestack MUST have the same input pixel layouts, and each channel MUST have the same bit-depth across all imagesheets. Pixel values sampled from a PNG file with a bitdepth of `N` bits will be normalized to +Imagestack objects, and thus all underlying `` elements, MUST follow one of the input pixel layouts shown in the table below. All imagesheets within an imagestack MUST have the same input pixel layouts, and each channel MUST have the same bit-depth across all imagesheets. Pixel values sampled from a PNG file with a bitdepth of `N` bits will be normalized to `pixelvalue / (2^N-1)`, i.e. a fully separated channel is normalized to 1, the minimum sampled value is normalized to 0. The following table shows the logical interpretation of sampling the "R", "G", "B" or "A"-channel depending on the input pixel layouts. The meaning of symbols is as follows: R – red, G – green, B – blue, A – alpha, Y – greyscale. @@ -355,15 +357,15 @@ The following table shows the logical interpretation of sampling the "R", "G", " | YA | Y | Y | Y | A | | Y | Y | Y | Y | 1 | -For example, if a function output from \ in a 3MF-file that maps to the R(ed) channel, but the referenced image is only monochromatic, then the greyscale channel is interpreted as the R color channel. Similarly, color values sampled from a monochromatic image are interpreted as if all "R", "G", "B" color channels share the same greyscale value. If there is no alpha channel present in the image, the highest possible value `1` MUST be used. +For example, if a function output from `` in a 3MF-file that maps to the R(ed) channel, but the referenced image is only monochromatic, then the greyscale channel is interpreted as the R color channel. Similarly, color values sampled from a monochromatic image are interpreted as if all "R", "G", "B" color channels share the same greyscale value. If there is no alpha channel present in the image, the highest possible value `1` MUST be used. -The \-element defines a voxel grid of values (e.g. RGB, grey-Alpha, grey) values distributed in a cuboid ({0,1,...,rowcount-1} x {0,1,...,columncount-1} x {0,1,...,sheetcount-1}). The left-front-bottom corner of this grid corresponds to the (0,0,0)-UVW coordinate when this 3D Image is being sampled, whereas the right-back-top corner corresponds to the (1,1,1) UVW-coordinate. Each \ corresponds to one PNG-file in the package. Figure 2-1 a) illustrates a voxel grid with `rowcount=3`, `columncount=4` and `sheetcount=2` voxels. Voxel indices are shown as bold black triple, the UVW-coordinate values as red triples. -Figure 2-1 b) illustrates the voxel indices and the UVW-values throughout the first \, Figure 2-1 c) illustrates these quantities throughout the second \. A voxel index triple `(i,j,k)` corresponds to a voxel with rowindex `i`, columnindex `j` and sheetindex `k`. +The ``-element defines a voxel grid of values (e.g. RGB, grey-Alpha, grey) values distributed in a cuboid ({0,1,...,rowcount-1} x {0,1,...,columncount-1} x {0,1,...,sheetcount-1}). The left-front-bottom corner of this grid corresponds to the (0,0,0)-UVW coordinate when this 3D Image is being sampled, whereas the right-back-top corner corresponds to the (1,1,1) UVW-coordinate. Each `` corresponds to one PNG-file in the package. Figure 2-1 a) illustrates a voxel grid with `rowcount=3`, `columncount=4` and `sheetcount=2` voxels. Voxel indices are shown as bold black triple, the UVW-coordinate values as red triples. +Figure 2-1 b) illustrates the voxel indices and the UVW-values throughout the first ``, Figure 2-1 c) illustrates these quantities throughout the second ``. A voxel index triple `(i,j,k)` corresponds to a voxel with rowindex `i`, columnindex `j` and sheetindex `k`. __Note__: The columnindex (`j`) relates to the UVW-coordinate `U`, whereas the rowindex `i` relates to the UVW-coordinate `V`. This definition is inline with the Materials and Properties specification https://github.com/3MFConsortium/spec_materials/blob/1.2.1/3MF%20Materials%20Extension.md#chapter-6-texture-2d. -The sampling rules for UVW values are determined by the filter-rule, and the behavior for UVW-values outside the unit-cube are determined by the tilestyle attributes [of the \](#32-functionfromimage3d). +The sampling rules for UVW values are determined by the filter-rule, and the behavior for UVW-values outside the unit-cube are determined by the tilestyle attributes [of the ``](#32-functionfromimage3d). _Figure 2-1: Voxel indixes and UVW-texture space of a sample voxel grid: a) shows a voxel grid of 3x4x2 voxels. b) shows a section view of the bottom voxels, c) shows a section view of the top voxels. The orange voxel at the right, front and bottom of a) has rowindex=2, columnindex=3 and sheetindex=0. d) shows the voxelcenters of this configuration._ ![Voxel indices and UVW-texture space of a sample voxel grid](images/image3dcoordinates.png) @@ -389,9 +391,9 @@ __Note__: Introductory information about the Open Packaging Conventions (OPC) ca It is RECOMMENDED that producers of 3MF Documents with the Volumetric Extension specification use the following part naming convention: -Paths of \ SHOULD consist of four segments. "/3D/volumetric/" as the first two segments, the name of a \-element that references this \ as third segment (for example "/3D/volumetric/mixingratios/", and the name of the imagesheet as last segment (for example "sheet0001.png"). Each part in the 3MF package that is referred to by the path of an \ MUST be associated with the 3D Model part via the 3D Texture relationship. +Paths of `` SHOULD consist of four segments. "/3D/volumetric/" as the first two segments, the name of a ``-element that references this `` as third segment (for example "/3D/volumetric/mixingratios/", and the name of the imagesheet as last segment (for example "sheet0001.png"). Each part in the 3MF package that is referred to by the path of an `` MUST be associated with the 3D Model part via the 3D Texture relationship. -This implies that all parts for \ in an imagestack SHOULD be located in the same OPC folder. +This implies that all parts for `` in an imagestack SHOULD be located in the same OPC folder. _Figure 2-3: OPC package layout_ ![OPC package layout](images/OPC_overview.png) @@ -406,19 +408,19 @@ Element **\** | --- | --- | --- | --- | --- | | path | ST\_UriReference | required | | Specifies the OPC part name (i.e. path) of the image data file | -Each \ element has one required attribute. The path property determines the part name (i.e. path) of the 2D image data (see chapter 6 of the Materials & Properties Extension specification for more information). +Each `` element has one required attribute. The path property determines the part name (i.e. path) of the 2D image data (see chapter 6 of the Materials & Properties Extension specification for more information). __Note__: -Other file formats like OpenVDB, OpenEXR, or VTK offer similar functionality as a stack of PNGs and are more efficient at doing so. However, their use in a manufacturing environment is hard as these formats are conceptually more complex and harder to implement. Therefore, this specification relies on the human readable and conceptually simpler stack of PNGs. Later versions of this extension, or private extension of the 3MF format MAY use different 3D image formats to encode a volumetric data as different child elements of \ and benefit from their advanced features. The remainder of this specification deals with the mapping of volumetric data onto mesh-objects in a 3MF file and giving this volumetric data a meaning for additive manufacturing processes. Adding a different data format for a voxel grid as child under \ would not affect the remaining parts of this specification. +Other file formats like OpenVDB, OpenEXR, or VTK offer similar functionality as a stack of PNGs and are more efficient at doing so. However, their use in a manufacturing environment is hard as these formats are conceptually more complex and harder to implement. Therefore, this specification relies on the human readable and conceptually simpler stack of PNGs. Later versions of this extension, or private extension of the 3MF format MAY use different 3D image formats to encode a volumetric data as different child elements of `` and benefit from their advanced features. The remainder of this specification deals with the mapping of volumetric data onto mesh-objects in a 3MF file and giving this volumetric data a meaning for additive manufacturing processes. Adding a different data format for a voxel grid as child under `` would not affect the remaining parts of this specification. # Chapter 5 LevelSet ### 5.1.1 LevelSet element A powerful application of Volumetric and Implicit modeling is the ability to define the shape of an object from volumetric information. Therefore we are introducing the concept of a **\** element which can be used to define the boundary of a shape using a levelset function. This is analogous to how a mesh defines the boundary between the inside and outside of the shape. In this case the mesh surface represents the surface of the levelset value equal to zero. -The child-element of the \-element references a functionID that must have a scalar output. This 'shape' represents the levelset function that MUST be evaluated to determine the actual shape of the object. +The child-element of the ``-element references a functionID that must have a scalar output. This 'shape' represents the levelset function that MUST be evaluated to determine the actual shape of the object. -Since fields can be evaluated in an unbounded way, a closed mesh is required to enclose any levelset element to make the evaluation space bounded. For example a simple box that represents the bounding box of the geometry encoded in the \-element. There are cases where a producer would want to specify a bounding box for evaluation. In that case one can set the the \-element to true and the \-element must be evaluated within the extents of the mesh referenced by the \-element. +Since fields can be evaluated in an unbounded way, a closed mesh is required to enclose any levelset element to make the evaluation space bounded. For example a simple box that represents the bounding box of the geometry encoded in the ``-element. There are cases where a producer would want to specify a bounding box for evaluation. In that case one can set the the ``-element to true and the ``-element must be evaluated within the extents of the mesh referenced by the ``-element. Element **\** @@ -426,25 +428,25 @@ Element **\** | Name | Type | Use | Default | Annotation | | -------------- | ------------ | -------- | ------- | -------------------------------------------------------------------- | -| functionid | ST_ResourceID| required | | ResourceID of the \ that provides the boundary as a level set. | +| functionid | ST_ResourceID| required | | ResourceID of the `` that provides the boundary as a level set. | | channel | xs:QName | required | | Name of the output of the function to be used for the levelset. The output must be a scalar | -| transform | ST_Matrix3D | | Identity | Transformation of the object coordinate system into the \ coordinate system. | +| transform | ST_Matrix3D | | Identity | Transformation of the object coordinate system into the `` coordinate system. | | minfeaturesize | ST_Number | | 0.0 | Specifies the minimum size of features to be considered in the boundary. | -| meshid | ST_ResourceID| required | | ResourceID of the \ that is used to define the evaluation domain of the level set.| +| meshid | ST_ResourceID| required | | ResourceID of the `` that is used to define the evaluation domain of the level set.| | meshbboxonly | xs:boolean | | false | Indicates whether to consider only the bounding box of the mesh for the level set. | | fallbackvalue | ST_Number | | 0.0 | Specifies the value to be used for this data element if the output of the referenced function is undefined | -| volumeid | ST_ResourceID | | | ResourceID of a \-Resource to apply on the object | +| volumeid | ST_ResourceID | | | ResourceID of a ``-Resource to apply on the object | -The \-element is used to describe the interior and exterior of an object via a levelset function. +The ``-element is used to describe the interior and exterior of an object via a levelset function. If meshbboxonly is set to true, the boundary is only intersected with the bounding box of the mesh. This allows the consumer to evaluate the boundary without computing the intersection with the mesh, otherwise the boundary is intersected with the mesh. -To simplify parsing, producers MUST define a \>-element prior to referencing it via the functionid-attribute in a \-element. +To simplify parsing, producers MUST define a ``>-element prior to referencing it via the functionid-attribute in a ``-element. **functionid**: -ResourceID of the \ that provides the boundary as a levelset. The function MUST have an input of type vector with the name "pos" and an output of type scalar that matches the name given as the channel attribute of the \ element. +ResourceID of the `` that provides the boundary as a levelset. The function MUST have an input of type vector with the name "pos" and an output of type scalar that matches the name given as the channel attribute of the `` element. **channel**: Defines which function output channel is used as the levelset function. The channel MUST be of type scalar. @@ -470,8 +472,8 @@ Any undefined result MUST be evaluated as the value provided. **VolumeDetermination** -_Figure 5-1: a) LevelSet A with a Mesh clipping surface. b) Mesh object B (rectangle) with \ child element Y. The mesh objects are defined in the order A-B. c) shows the volume defined by the overlapped mesh objects. d) shows \ child element X in object A, and \ child element Y in object B. The table lays out how these \ child elements are sampled at positions p1 to p4._ -![Illustration of overlapping meshes with \ child elements](images/overlap_properties.png) +_Figure 5-1: a) LevelSet A with a Mesh clipping surface. b) Mesh object B (rectangle) with `` child element Y. The mesh objects are defined in the order A-B. c) shows the volume defined by the overlapped mesh objects. d) shows `` child element X in object A, and `` child element Y in object B. The table lays out how these `` child elements are sampled at positions p1 to p4._ +![Illustration of overlapping meshes with `` child elements](images/overlap_properties.png) # Chapter 6. Volumetric Data @@ -482,7 +484,7 @@ Element **\** ![mesh XML structure](images/element_mesh.png) -The volumetric data \ element is a new OPTIONAL element which extends is a type of resource to be used by a Shape (i.e. the \ element). +The volumetric data `` element is a new OPTIONAL element which extends is a type of resource to be used by a Shape (i.e. the `` element). ## 6.2. Volumetric Data @@ -491,18 +493,18 @@ Element **\** ![volumedata XML structure](images/element_volumedata.png) -The \ defines the volumetric properties in the interior of a \ element. +The `` defines the volumetric properties in the interior of a `` element. -The child-element of the \ element reference a function, that has to match the signature requirements of the child element. -Volumedata MUST only be referenced by an object type "mesh" or "levelset" unless explicitly allowed by shapes defined in other extensions. This ensures that the \ applies to a volume. +The child-element of the `` element reference a function, that has to match the signature requirements of the child element. +Volumedata MUST only be referenced by an object type "mesh" or "levelset" unless explicitly allowed by shapes defined in other extensions. This ensures that the `` applies to a volume. Moreover, the volumedata-element MUST not be used in a mesh that is referenced as "originalmesh" by any other mesh. This excludes the possibility to implicitly mirror volumedata, which makes it easier to consume files with this extension. -The \ element can contain up to one \ child element, up to one \ element, and up to 2^31-1 of \ elements. +The `` element can contain up to one `` child element, up to one `` element, and up to 2^31-1 of `` elements. -The child elements modify the enclosing \ by specifying color, material composition and other arbitrary properties of the \ object. +The child elements modify the enclosing `` by specifying color, material composition and other arbitrary properties of the `` object. -To rationalize how this specification modifies the definition of geometry within a 3MF model, the concept of a "clipping surface" of a mesh with a \ element is introduced. -The clipping surface is defined by the surface of the enclosing \ element. This implicitly takes into account any geometry defined by e.g. the beamlattices specification. +To rationalize how this specification modifies the definition of geometry within a 3MF model, the concept of a "clipping surface" of a mesh with a `` element is introduced. +The clipping surface is defined by the surface of the enclosing `` element. This implicitly takes into account any geometry defined by e.g. the beamlattices specification. This clipping surface trims any volumetric data defined therein. Any data outside the clipping surface MUST be ignored. The geometry that should be printed is defined by the interior of the clipping surface. @@ -518,11 +520,11 @@ Defining conflicting surface- and volumetric properties can be very powerful, e. The properties at surface regions that are not explicitly specified are instead given by the volumetric properties. Conflicting properties must be handled as follows: -1. Producers MUST not define colors, materials or properties via child elements of the \ element that are impossible on physical grounds (e.g. non-conducting copper). +1. Producers MUST not define colors, materials or properties via child elements of the `` element that are impossible on physical grounds (e.g. non-conducting copper). 2. Consumers that read files with properties that cannot be realized due to limitations specific to them (e.g. a specific manufacturing device that does not support a material in a specific color), SHOULD raise a warning, but MAY handle this in any appropriate way for them. If there is an established process between Producer and Consumer, resolution of such conflicts SHOULD be performed e.g. via negotiation through printer capabilities and a print ticket. -__Note__: In the case where objects with different \ child elements overlap, only the \ child elements from last object can be used. -This makes sure that \ child elements of an overlapped object do not determine the value of any \ child elements of an overlapping object. Figure 5-1 illustrates this behavior. +__Note__: In the case where objects with different `` child elements overlap, only the `` child elements from last object can be used. +This makes sure that `` child elements of an overlapped object do not determine the value of any `` child elements of an overlapping object. Figure 5-1 illustrates this behavior. ### 6.2.1 Color element @@ -533,14 +535,14 @@ Element **\** | Name | Type | Use | Default | Annotation | | --------------- | -------------- | -------- | ------- | --------------------------------------------------------- | || functionid | ST_ResourceID | required | | Model Resource Id of the function providing the color | -| transform | ST_Matrix3D | | | Transformation of the object coordinate system into the \ coordinate system. | +| transform | ST_Matrix3D | | | Transformation of the object coordinate system into the `` coordinate system. | | channel | xs:QName | required | | Name of the function ouput to be used as color. The output must be of type vector | | minfeaturesize | ST_Number | | 0.0 | Hint for the minimum size of features. | | fallbackvalue | ST_Number | | 0.0 | Specifies the value to be used for this data element if the output of the referenced function is undefined | -To simplify parsing, producers MUST define a \-element prior to referencing it via the vector3dfieldid in a \-element. +To simplify parsing, producers MUST define a ``-element prior to referencing it via the vector3dfieldid in a ``-element. -The \ element is used to define the color of the object. +The `` element is used to define the color of the object. The color MUST be interpreted in linearized sRGB color space as defined in the Materials and Properties specification https://github.com/3MFConsortium/spec_materials/blob/1.2.1/3MF%20Materials%20Extension.md#12-srgb-and-linear-color-values. The vector components `x`, `y` and `z` of the 3D vector field are interpreted as the "R", "G" and "B" channels of the color of the enclosing meshobject, respectively. If either channel evaluates to a value \<0 or \>1 it has to be truncated at 0 or 1, respectively. @@ -550,7 +552,7 @@ This specification does not capture well the properties for semi-transparent, di **transform**: The transformation of the object coordinate system into the coordinate system of the function (e.g. noramlized coordinates for functionFromImage3D). -If this \>-element is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the 3D vector field must be sampled at position `(x',y',z') = T*(x,y,z)`. +If this ``>-element is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the 3D vector field must be sampled at position `(x',y',z') = T*(x,y,z)`. **channel** @@ -572,22 +574,22 @@ Element **\** | Name | Type | Use | Default | Annotation | | --- | --- | --- | --- | --- | -| basematerialid | ST\_ResourceID | required | | ResourceID of the \ element that holds the \-elements referenced in the child \-elements. | +| basematerialid | ST\_ResourceID | required | | ResourceID of the `` element that holds the ``-elements referenced in the child ``-elements. | -The \ element describes a mixing ratio of printer materials at each position in space. The CONSUMER can determine the halftoning, mixing or dithering strategy that can be used to achieve these mixtures. +The `` element describes a mixing ratio of printer materials at each position in space. The CONSUMER can determine the halftoning, mixing or dithering strategy that can be used to achieve these mixtures. -This element MUST contain at least one \ element, which will encode the relative contribution of a specific basematerial to the material mix. +This element MUST contain at least one `` element, which will encode the relative contribution of a specific basematerial to the material mix. -The number of \-elements in the \ element referenced by a \ element MUST equal the number of \-elements in the \ element. To simplify parsing, producers MUST define the referenced \-element prior to referencing it via the basematerialid in a \-element. +The number of ``-elements in the `` element referenced by a `` element MUST equal the number of ``-elements in the `` element. To simplify parsing, producers MUST define the referenced ``-element prior to referencing it via the basematerialid in a ``-element. -Producers MUST NOT create files where the sum of all values in its child \-elements is smaller than `10^-5`. If the total is smaller than this threshold, the mixing ratio is up to the consumer. +Producers MUST NOT create files where the sum of all values in its child ``-elements is smaller than `10^-5`. If the total is smaller than this threshold, the mixing ratio is up to the consumer. - If there are `N` materials, then the mixing ration of material `i` at point `X` is given by: ``` value of channel i / sum(value of all N mixing contributions at point X) ``` -The order of the -elements defines an implicit 0-based index. This index corresponds to the index defined by the \- elements in the \-element of the core specification. +The order of the -elements defines an implicit 0-based index. This index corresponds to the index defined by the ``- elements in the ``-element of the core specification. ## 6.2.3 Material mapping element @@ -597,20 +599,20 @@ Element **\** | Name | Type | Use | Default | Annotation | | -------------- | ------------- | -------- | ------- | --------------------------------------------------------- | -| functionid | ST_ResourceID | required | | ResourceID of the \ providing the mixing contribution value for a material in the \-element. | -| transform | ST_Matrix3D | | | Transformation of the object coordinate system into the \ coordinate system | +| functionid | ST_ResourceID | required | | ResourceID of the `` providing the mixing contribution value for a material in the ``-element. | +| transform | ST_Matrix3D | | | Transformation of the object coordinate system into the `` coordinate system | | channel | xs:QName | required | | Name of the function output to be used for the mixing contribution. The output must be a scalar. | | minfeaturesize | ST_Number | | 0 | Hint for the minimum size of features. | | fallbackvalue | ST_Number | | 0.0 | Specifies the value to be used for this data element if the output of the referenced function is undefined | -The \ element defines the relative contribution of a specific material to the mixing of materials in it's parent \-element. +The `` element defines the relative contribution of a specific material to the mixing of materials in it's parent ``-element. -To simplify parsing, producers MUST define the referenced \-element prior to referencing it via the functionid in a \-element. +To simplify parsing, producers MUST define the referenced ``-element prior to referencing it via the functionid in a ``-element. **transform**: The transformation of the object coordinate system into the scalar field coordinate system. -If any channel of a \ is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the referenced scalar field must be sampled at position `(x',y',z') = T*(x,y,z)`. +If any channel of a `` is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the referenced scalar field must be sampled at position `(x',y',z') = T*(x,y,z)`. **channel**: @@ -624,7 +626,7 @@ The minimum size of features to be considered in the mixing contribution. This i If this attribute is set, any undefined result MUST be evaluated as the value. -If the sampled value of a \ is `<0` it must be evaluated as "0". +If the sampled value of a `` is `<0` it must be evaluated as "0". ### 6.2.4 Property element @@ -634,21 +636,21 @@ Element **\** | Name | Type | Use | Default | Annotation | | --- | --- | --- | --- | --- | -| functionid | ST\_ResourceID | required | | ResourceID of the \ that provides the value of this property | -| transform | ST\_Matrix3D | | | Transformation of the object coordinate system into the \ coordinate system | +| functionid | ST\_ResourceID | required | | ResourceID of the `` that provides the value of this property | +| transform | ST\_Matrix3D | | | Transformation of the object coordinate system into the `` coordinate system | | channel | xs:QName | required | | Name of the function output to be used for the property. | -| name | xs:QName | required | | Contains either the name of the property, defined in a 3MF extension specification, or the name of a vendor-defined property. Either MUST be prefixed with a valid XML namespace name declared on the \ element. | +| name | xs:QName | required | | Contains either the name of the property, defined in a 3MF extension specification, or the name of a vendor-defined property. Either MUST be prefixed with a valid XML namespace name declared on the `` element. | | required | xs:boolean | | false | Indicator whether this property is required to process this 3MF document instance. | | fallbackvalue | ST_Number | | 0.0 | Specifies the value to be used for this data element if the output of the referenced function is undefined | -The \ element allows to assign any point in space a scalar or vectorial value of a freely definable property. This can be used to assign, e.g. opacity, conductivity, or translucency. +The `` element allows to assign any point in space a scalar or vectorial value of a freely definable property. This can be used to assign, e.g. opacity, conductivity, or translucency. -To simplify parsing, producers MUST define the referenced \-element prior to referencing it via the functionid in a \-element. +To simplify parsing, producers MUST define the referenced ``-element prior to referencing it via the functionid in a ``-element. **transform**: -The transformation of the object coordinate system into the \ coordinate system. -If a \-element is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the referenced \ must be sampled at position `(x',y',z') = T*(x,y,z)`. +The transformation of the object coordinate system into the `` coordinate system. +If a ``-element is being sampled at position `(x,y,z)` in the mesh's local object coordinate system, the referenced `` must be sampled at position `(x',y',z') = T*(x,y,z)`. **channel**: @@ -658,19 +660,19 @@ This specification does not provide qualified names for such properties as part A later extension of the 3MF format might define such qualified names as part of a different extension specification or a later version of the volumetric extension specification. Producers that want to specify such properties now, SHOULD define a qualified name that can e.g. be called "http://www.vendorwwebsite.com/3mf/vendor13mfextension/2021/05". The specifications of private namespaces (that are not ratified by the 3MF Consortium) MUST be negotiated between producer and consumer of a 3MF file. -The names of \-elements MUST be unique within a \. This name MUST be prefixed with a valid XML namespace name declared on the element. +The names of ``-elements MUST be unique within a ``. This name MUST be prefixed with a valid XML namespace name declared on the element. The interpretation of the value MUST be defined by the owner of the namespace. __Note__: -The producer of a 3MF file is responsible for assembling the values in the \ (and the referenced \ such that sampling it in the print-bed coordinate system as a e.g. physical property, is sensible. This requirement is particularly important if the accumulated transformation `T0` between print-bed coordinates and local object coordinates is not a rigid body transformation. +The producer of a 3MF file is responsible for assembling the values in the `` (and the referenced `` such that sampling it in the print-bed coordinate system as a e.g. physical property, is sensible. This requirement is particularly important if the accumulated transformation `T0` between print-bed coordinates and local object coordinates is not a rigid body transformation. (The transformation `T0` of the print-bed coordinate system into the object coordinate system is given by the `transform`-attributes on the `item` and `component`-elements in the path that leads to this object in the `build`-hierarchy of the 3MF Core Specification (see https://github.com/3MFConsortium/spec_core/blob/1.3.0/3MF%20Core%20Specification.md#3431-item-element and https://github.com/3MFConsortium/spec_core/blob/1.3.0/3MF%20Core%20Specification.md#421-component, and Figure 6.2 in this document). If the interpretation of a property might result in a conflict with the standard volumedata-elements (boundary, color, composite) the namespace-owner MUST specify a resolution to the conflict. A producer MUST NOT create files with properties that conflict with each other. If a physical unit is necessary, the namespace owner MUST define a unique and unambiguous physical unit system for the namespace. The unit system SHOULD be metric. -If a \ is marked as `required`, and a consumer does not support it, it MUST warn the user or the appropriate upstream processes that it cannot process all contents in this 3MF document instance. -Producers of 3MF files MUST mark all volumetric \-elements required to represent the design intent of a model as `required`. +If a `` is marked as `required`, and a consumer does not support it, it MUST warn the user or the appropriate upstream processes that it cannot process all contents in this 3MF document instance. +Producers of 3MF files MUST mark all volumetric ``-elements required to represent the design intent of a model as `required`. # Chapter 7. Notes @@ -684,20 +686,20 @@ It is RECOMMENDED that calculations during evaluation of the graph are performed Equipped with the language elements of this specification, one can recapitulate the core concepts with an overview of the sampling process. -Figure 7-1 illustrates the 3MF elements, the different coordinate systems and transforms between them when a \ element (in this case \) is sampled in the object coordinate space. +Figure 7-1 illustrates the 3MF elements, the different coordinate systems and transforms between them when a `` element (in this case ``) is sampled in the object coordinate space. Figure 7-1 a) The object's color is sampled at position (+) in the print-bed coordinate system. The clipping surface is hinted at with a wireframe. The transformation `T0` of the print-bed coordinate system into the object coordinate system is given by the `transform`-attributes on the `item` and `component`-elements in the path that leads to this object in the `build`-hierarchy of the 3MF Core Specification (see https://github.com/3MFConsortium/spec_core/blob/1.3.0/3MF%20Core%20Specification.md#3431-item-element and https://github.com/3MFConsortium/spec_core/blob/1.3.0/3MF%20Core%20Specification.md#421-component). -Figure 7-1 b) shows the \ underlying the color of the object. The sampling point is represented in the coordinate system of the \. The transformation `T1` from object coordinate space to \ coordinate system is given by the `transform`-element in the \-element. The original clipping surface from a) is only shown for illustration porpuses. It does not exist in the \ context. -The color value sampled in this illustration directly originates from a \ element. +Figure 7-1 b) shows the `` underlying the color of the object. The sampling point is represented in the coordinate system of the ``. The transformation `T1` from object coordinate space to `` coordinate system is given by the `transform`-element in the ``-element. The original clipping surface from a) is only shown for illustration porpuses. It does not exist in the `` context. +The color value sampled in this illustration directly originates from a `` element. -Figure 7-1 c) Shows the \ again. The unit box of the UVW coordinate system is shown as a wireframe. The transformation `T2` between \ coordinate system and UVW space is given according to the `transform`-attribute of the \ element. +Figure 7-1 c) Shows the `` again. The unit box of the UVW coordinate system is shown as a wireframe. The transformation `T2` between `` coordinate system and UVW space is given according to the `transform`-attribute of the `` element. -Figure 7-1 d) Shows the UVW coordinate space of the \-element and where the sampling point (+) is evaluated, and the UVW-locations to which the voxel centers of the underlying \-element map. +Figure 7-1 d) Shows the UVW coordinate space of the ``-element and where the sampling point (+) is evaluated, and the UVW-locations to which the voxel centers of the underlying ``-element map. -Figure 7-1 e) illustrates where the sampling point (+) ends up in the voxel index space of the \. The mapping of UVW to voxel indices in the \-element is described in [Chapter 2. 3D Image](#chapter-2-3d-image). +Figure 7-1 e) illustrates where the sampling point (+) ends up in the voxel index space of the ``. The mapping of UVW to voxel indices in the ``-element is described in [Chapter 2. 3D Image](#chapter-2-3d-image). -_Figure 7-1: Illustration of the different coordinate systems and 3MF elements in the sampling process. a) the object to be sampled at position (+). b) A view into the \. The original clipping surface from a) is only shown for illustration porpuses. c) Shows the \ again. The unit box of the UVW coordinate system is shown as a wireframe. d) The UVW coordinate space and the UVW-locations to which the voxel-centers map. e) The sampling point (+) in the voxel index space._ +_Figure 7-1: Illustration of the different coordinate systems and 3MF elements in the sampling process. a) the object to be sampled at position (+). b) A view into the ``. The original clipping surface from a) is only shown for illustration porpuses. c) Shows the `` again. The unit box of the UVW coordinate system is shown as a wireframe. d) The UVW coordinate space and the UVW-locations to which the voxel-centers map. e) The sampling point (+) in the voxel index space._ ![Illustration of different coordinate systems in the sampling process](images/fig_coordinatesystems.png) ## 7.3. Limitations @@ -728,50 +730,50 @@ The _implicit_ namespace enhances the _volumetric extension_ by providing a way When used as input for ``, the functions are evaluated at each point within the mesh or its bounding box. These functions are constructed through a graph-connected node set that is connected to both the function's inputs and outputs. Some of node types allow the usage of other resources, like computing the signed distance to mesh. Also a functionFromImage3D can be called from inside of a function. Consider an example: +![implicit function of a sphere](images/sphere_graph.png) ```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + ``` -In this example, the _function_ representing a sphere takes two inputs, 'pos' and 'radius'. It showcases the flexibility of defining various mathematical operations like length computation and subtraction through nested nodes within the function. The result of these computations can be accessed through the 'outputs' member. +In this example, the _function_ representing a sphere takes two inputs, a vector 'pos' and a scalar value 'radius'. + +Links are defined by back-referencing the output of one node to the input of another node. + +The 'length' node computes the length of the input vector 'pos'. The connection to the input vector 'pos' is established through the 'vectorref' element. References have the format [nodename].[outputname]. In the case of funcion arguments the nodename is the resesrved name 'inputs'. + +The 'subtraction' node computes the difference between the length of the input vector 'pos' and the scalar value 'radius'. The connection to the length output is established through the 'scalarref' element. + +The 'out' element defines the output of the function. The connection to the subtraction output is established through the 'scalarref' element. + +It showcases the flexibility of defining various mathematical operations like length computation and subtraction through nested nodes within the function. The result of these computations can be accessed through the member. + Furthermore, a function can include basic mathematical operations like additions, subtractions, and multiplications to cosines, logarithms or clamping. The operations can use different types like scalars, vectors, and matrices. @@ -871,15 +873,17 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - + + + + + + + + + + + ``` @@ -890,11 +894,13 @@ The operation can be used for the following types of inputs and outputs: Example: ```xml - - - - - + + + + + + + ``` **Inputs:** @@ -935,11 +941,13 @@ None **Example Usage:** ```xml - - - - - + + + + + + + ``` ## constmat @@ -965,15 +973,17 @@ None **Example Usage:** ```xml - - - - - + + + + + ``` # constresourceid @@ -999,11 +1009,13 @@ None **Example Usage:** ```xml - - - - - + + + + + + + ``` ## composevector @@ -1027,16 +1039,18 @@ None **Example Usage:** ```xml - - - - - - - - - - + + + + + + + + + + + + ``` ## vectorfromscalar @@ -1058,14 +1072,16 @@ None **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## decomposevector @@ -1089,16 +1105,18 @@ None **Example Usage:** ```xml - - - - - - - - - - + + + + + + + + + + + + ``` ## composematrix @@ -1122,29 +1140,31 @@ None **Example Usage:** ```xml - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + ``` ## matrixfromcolumns @@ -1174,17 +1194,19 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - - - + + + + + + + + + + + + + ``` ## matrixfromrows @@ -1212,17 +1234,19 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - - - + + + + + + + + + + + + + ``` ## multiplication @@ -1251,16 +1275,18 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** -```xml - - - - - - - - - +```xml + + + + + + + + + + + ``` ## subtraction @@ -1289,16 +1315,18 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** -```xml - - - - - - - - - +```xml + + + + + + + + + + + ``` ## division @@ -1329,15 +1357,17 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - + + + + + + + + + + + ``` ## dot @@ -1366,15 +1396,17 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - + + + + + + + + + + + ``` ## cross @@ -1403,15 +1435,17 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - + + + + + + + + + + + ``` ## matrixvectormultiplication @@ -1439,15 +1473,17 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml + - - - - - - - + + + + + + + + ``` ## transpose @@ -1475,14 +1511,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## inverse @@ -1508,14 +1546,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## sin @@ -1544,14 +1584,16 @@ The operation can be used for the following types of inputs and outputs: Example usage: ```xml - - - - - - - - + + + + + + + + + + ``` ## cos @@ -1580,14 +1622,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## tan @@ -1616,14 +1660,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## arcsin @@ -1652,14 +1698,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## arccos @@ -1688,14 +1736,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## arctan @@ -1726,14 +1776,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## arctan2 @@ -1763,15 +1815,17 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - + + + + + + + + + + + ``` ## min @@ -1802,15 +1856,17 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - + + + + + + + + + + + ``` ## max @@ -1841,15 +1897,17 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - + + + + + + + + + + + ``` ## abs @@ -1879,14 +1937,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` @@ -1915,16 +1975,18 @@ The operation can be used for the following types of inputs and outputs: | matrix | matrix | matrix | modulo operation of each component of the matrices| **Example Usage:** -```xml - - - - - - - - - +```xml + + + + + + + + + + + ``` ## mod @@ -1950,16 +2012,18 @@ The operation can be used for the following types of inputs and outputs: | matrix | matrix | matrix | modulo operation of each component of the matrices| **Example Usage:** -```xml - - - - - - - - - +```xml + + + + + + + + + + + ``` @@ -1990,15 +2054,17 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - + + + + + + + + + + + ``` ## sqrt @@ -2024,14 +2090,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## mesh @@ -2058,15 +2126,17 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - + + + + + + + + + + + ``` ## unsignedmesh @@ -2093,15 +2163,17 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - + + + + + + + + + + + ``` ## length @@ -2129,14 +2201,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## log @@ -2166,14 +2240,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## log2 @@ -2203,14 +2279,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## log10 @@ -2235,14 +2313,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## exp @@ -2267,14 +2347,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## cosh @@ -2304,14 +2386,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## sinh @@ -2341,14 +2425,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## tanh @@ -2378,14 +2464,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## clamp @@ -2417,16 +2505,18 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - - - + + + + + + + + + + + + ``` ## select @@ -2458,17 +2548,19 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - + + + + + + + + + + + + + ``` ## round @@ -2498,14 +2590,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## ceil @@ -2535,14 +2629,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## floor @@ -2572,14 +2668,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## sign @@ -2608,14 +2706,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## fract @@ -2644,14 +2744,16 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + ``` ## functionCall @@ -2673,15 +2775,43 @@ The operation can be used for the following types of inputs and outputs: **Example Usage:** ```xml - - - - - - - - + + + + + + + + + + +``` + +Calling the sphere function from the example in [Chapter 2. Function Implicit](#chapter-2-function-implicit) could look like this: + +```xml + + + + + + + + + + + + + + + + + + + + ``` +The inputs of the sphere function are added as inputs to the function call node. The output of the function call node is the output of the sphere function. A constresourceid node is used to define the functionID of the sphere function. Note that a resourceid could also be used as a function input. ## Chapter 5. Implicit Evaluation @@ -3050,7 +3180,6 @@ _sheet0.png_ minOccurs="2" maxOccurs="2" /> - @@ -6132,4 +6261,4 @@ _sheet1.png_ See also [the standard 3MF References](https://github.com/3MFConsortium/spec_resources/blob/master/references.md). -Copyright 3MF Consortium 2023. +Copyright 3MF Consortium 2024.