Merge pull request #304 from asam-ev/Complete-linguistic-review

Complete linguistic review

content/bibliography.bib

@@ -45,3 +45,7 @@ @misc{EPSG
     title  = {https://epsg.io[Coordinate Systems Worldwide^]},
     note   = {[viewed 2024-03-18]}
 }
+
+@Standard{uui,
+    title  = {https://en.wikipedia.org/wiki/Universally_unique_identifier[__Wikipedia__^], Universally unique identifier}
+}

content/general-docs/backward-compatibility.adoc

@@ -6,6 +6,5 @@ ifndef::include-only-once[]
 include::{root-path}_config.adoc[]
 endif::[]
 
-{THIS_STANDARD} is backwards compatible with {THIS_STANDARD}
-
-
+This is the first release of this standard published by ASAM.
+Therefore, no information about the backward compatibility of this standard has been added to this section.

content/general-docs/introduction.adoc

@@ -30,11 +30,11 @@ Standardization efforts have been made for scenarios and road data using ASAM Op
 
 === The two main chapters of {THIS_STANDARD}
 
-{THIS_STANDARD} is divided into distinct yet complementary chapters enabling a modular approach to implementation. Key to this is the distinction between Material and Geometry. Based on specific use-cases, users of {THIS_STANDARD} can implement the standard for one or both chapters.  At least one of the two chapters shall be implemented to conform with the standard.
+{THIS_STANDARD} is divided into distinct yet complementary chapters enabling a modular approach to implementation. Key to this is the distinction between material and geometry. Based on specific use-cases, users of {THIS_STANDARD} can implement the standard for one or both chapters.  At least one of the two chapters shall be implemented to conform with the standard.
 
-* *Material*: This chapter includes definitions and file formats for storing and exchanging material properties. These properties can be physical, such as surface roughness, permittivity, and index of refraction, or measured data, like wavelength and angle-dependent reflectance values. Tools or systems focusing on material properties can implement support for the Material chapter. For example: “This tool supports {THIS_STANDARD}: Material”.
+* *Material*: This chapter includes definitions and file formats for storing and exchanging material properties. These properties can be physical, such as surface roughness, permittivity, and index of refraction, or measured data, like wavelength and angle-dependent reflectance values. Tools or systems focusing on material properties can implement support for the material chapter. For example: “This tool supports {THIS_STANDARD}: Material”.
 
-* *Geometry*: This chapter contains structures for different object classes. These structures define uniform node structure, naming scheme and coordinate systems to enable exchange, common integration and animation of 3D models. Tools or systems working primarily with geometric data, such as 3D models or spatial structures, can implement support for the Geometry chapter. For example: “This tool supports {THIS_STANDARD}: Geometry”.
+* *Geometry*: This chapter contains structures for different object classes. These structures define uniform node structure, naming scheme and coordinate systems to enable exchange, common integration and animation of 3D models. Tools or systems working primarily with geometric data, such as 3D models or spatial structures, can implement support for the geometry chapter. For example: “This tool supports {THIS_STANDARD}: Geometry”.
 
 * *Full Compliance*: For a full exchange of simulation-ready 3D assets however, both chapters must be supported. Systems or tools providing full support for both material and geometric data can be described as follows: “This tool supports {THIS_STANDARD}”.
 
@@ -44,8 +44,8 @@ A list of use cases examples can be found in the https://asam-ev.github.io/OpenM
 
 {THIS_STANDARD} defines various file formats for specifying assets, _material properties_, and the mapping between them.
 <<fig-openmaterial-overview>> illustrates these file formats and their interconnections.
-The definitions of the geometry related data formats marked in red can be found in xref:geometry/geometry-index.adoc[].
-The definitions of the _material_ related data formats marked in blue can be found in xref:material/material-index.adoc[].
+The definitions of the geometry related data formats marked in red can be found in the geometry chapter.
+The definitions of the _material_ related data formats marked in blue can be found in the material chapter.
 
 [#fig-openmaterial-overview]
 .Overview of {THIS_STANDARD} file formats and data flow
@@ -55,7 +55,7 @@ The first interaction with an {THIS_STANDARD}-compliant _3D model_ is through th
 
 The *asset file* is a JSON file with the file extension .xoma ({THIS_STANDARD} Asset).
 A detailed definition of the https://github.com/asam-ev/OpenMATERIAL/blob/main/schemas/asset_schema.json[asset file JSON schema] is given in xref:geometry/asset-schema.adoc[].
-The asset file shall have the same name as a corresponding 3D data file in glTF, FBX or USD format.
+The asset file shall have the same name as a corresponding 3D data file in glTF, FBX, or USD format.
 To facilitate instancing, multiple asset file may be linked to a single _3D model_ file by adding an index separated by a dot (.) as a suffix to the asset file name.
 It contains metadata, such as description, unique identifier, version information, copyright details, and so on.
 It also includes a _material_ texture assignment table, allowing dedicated _material_ mapping textures to be assigned to materials within 3D data files.
@@ -65,10 +65,10 @@ For the mapping currently only the rba channels are used (first 24 Bit).
 The last channel is reserved for future use.
 An https://github.com/asam-ev/OpenMATERIAL/tree/main/examples/example_asset.xoma[example asset] is provided in the examples folder of the repository.
 
-The *3D data file* is a standard _3D model_ file in glTF, FBX or USD format.
+The *3D data file* is a standard _3D model_ file in glTF, FBX, or USD format.
 Multiple formats can exist in parallel, so one asset file can have multiple 3D data files with different formats with the same name as the asset file.
-However, to be standard compliant, a simulation environment must support at least one of the named 3D data formats.
-More information about the file formats is given in is given in xref:geometry/file-format-support.adoc[].
+However, to be compliant with {THIS_STANDARD}, a simulation environment must support at least one of the named 3D data formats.
+More information about the file formats is given in in xref:geometry/file-format-support.adoc[].
 An https://github.com/asam-ev/OpenMATERIAL/tree/main/examples/example_asset.gltf[example model] is provided in the examples folder of the repository.
 
 The *material mapping file* is separated from the asset file to facilitate reusability.
@@ -104,7 +104,7 @@ Examples for _material property_ files and look-up table files are provided in t
 
 To ensure compliance with the {THIS_STANDARD} specification, users need to be able to distinguish between requirements, recommendations, permissions, possibilities and capabilities, and external constraints.
 
-The following rules for using modal verbs apply:
+The rules listed in <<tab-modal-verbs>> for using modal verbs apply:
 
 [#tab-modal-verbs]
 .Verbal forms for expressions of provisions
@@ -165,9 +165,9 @@ Notes, footnotes, and examples shall not contain requirements or any information
 
 The following deliverables are provided for {THIS_STANDARD}:
 
-* https://asam-ev.github.io/OpenMATERIAL/asamopenmaterial/latest/specification/index.html[{THIS_STANDARD} BS 1-0-0 Specification, 2025-MM-DD] (this document, contained in this site)
-* https://github.com/asam-ev/OpenMATERIAL/tree/main/schemas[JSON schema files] for all json formats (contained in the open-source standard repository)
-* https://github.com/asam-ev/OpenMATERIAL/tree/main/examples[Example files] for all defined file formats (contained in the open-source standard repository) and further examples of
-** a https://github.com/asam-ev/OpenMATERIAL/tree/main/examples/vehicle_example[vehicle] (contained in the open-source standard repository)
-** a https://github.com/asam-ev/OpenMATERIAL/tree/main/examples/human_example[human] (contained in the open-source standard repository)
-** an https://github.com/asam-ev/OpenMATERIAL/tree/main/examples/environment_example[environment] (contained in the open-source standard repository)
+* https://asam-ev.github.io/OpenMATERIAL/asamopenmaterial/latest/specification/index.html[{THIS_STANDARD}® BS 1-0-0 Specification, 2025-MM-DD] (this document, contained in this site)
+* https://github.com/asam-ev/OpenMATERIAL/tree/main/schemas[JSON schema files] for all json formats (contained in the {THIS_STANDARD} Github repository)
+* https://github.com/asam-ev/OpenMATERIAL/tree/main/examples[Example files] for all defined file formats (contained in the {THIS_STANDARD} Github repository) and further examples of
+** a https://github.com/asam-ev/OpenMATERIAL/tree/main/examples/vehicle_example[vehicle] (contained in the {THIS_STANDARD} Github repository)
+** a https://github.com/asam-ev/OpenMATERIAL/tree/main/examples/human_example[human] (contained in the {THIS_STANDARD} Github repository)
+** an https://github.com/asam-ev/OpenMATERIAL/tree/main/examples/environment_example[environment] (contained in the {THIS_STANDARD} Github repository)

content/general-docs/scope.adoc

@@ -8,7 +8,7 @@ endif::[]
 
 {THIS_STANDARD} specifies the following:
 
-* Structure and coordinate frames for _3D models_ (*3D Data Files*), supporting common 3D exchange formats such as FBX, glTF; and USD. 
+* Structure and coordinate frames for _3D models_ (*3D Data Files*), supporting common 3D exchange formats such as FBX, glTF, and USD. 
 * Metadata for _3D models_ and references to *Material Mapping Files* based on JSON schemas in *Asset Files*.
 * _Material_ mapping based on JSON schemas in *Material Mapping Files*.
 * Physics-based or measured _material properties_ based on JSON schemas in *Material Data Files*.

content/geometry/file-format-support.adoc

@@ -14,7 +14,7 @@ However, the geometry specification defines coordinate systems, units, node hier
 
 glTF::
 _3D models_ of {THIS_STANDARD} in glTF format shall comply with the official https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html[glTF specification].
-The glTF specification has two delivery options: glTF + bin + textures and the container format glb.
+The glTF specification has two delivery options: glTF + bin + textures, and the container format glb.
 Both delivery options are supported in {THIS_STANDARD}.
 +
 The glTF coordinate system is right-handed, with +Y as the up axis, +Z as forward, and -X as right. The front of a glTF asset faces +Z. 

content/geometry/general.adoc

@@ -35,7 +35,7 @@ Unless stated otherwise, all numeric values within {THIS_STANDARD} are in SI uni
 
 Both coordinate systems consist of three orthogonal directions associated with
 x-, y-, and z-axes, and a coordinate origin where axes meet. The coordinate
-systems are right-handed Cartesian coordinate systems according to ISO 8855. For
+systems are right-handed Cartesian coordinate systems according to ISO 8855 cite:[iso8855]. For
 a non-rotated coordinate system, the following applies:
 
 * Forward matches x-axis
@@ -120,60 +120,63 @@ The following naming conventions apply to {THIS_STANDARD} geometry files:
 === Node structure
 
 Every node structure for a 3D object uses predefined keywords to allow a consistent naming convention and parsing.
-Some keywords are already defined by the standard and more could follow in future updates.
-The user is free to add more keywords for himself, if they are needed.
+Some keywords are already defined by the {THIS_STANDARD} standard and more could follow in future updates.
+Users are free to add more keywords for themself, if they are needed. The following rules apply:
 
-* All components shall be named according to the capital Snake_Case definition, starting with uppercase letters.
+* All components shall be named according to capital snake case definition, starting with uppercase letters.
 * Group nodes (also known as empty nodes or parent nodes) shall have "Grp_" as a prefix.
-* Iterators are added as suffixes.
-  In the documentation, iterator names are written in pointy braces. Example: <type_idx>.
-  In the node names itself, the iterator names are replaced by integer values starting from 0.
+* Iterators shall be added as suffixes.
+  In the documentation, iterator names are written in angled brackets. Example: <type_idx>.
+  In the node names itself, the iterator names are replaced by integer values, starting from 0.
 * Sequence of suffixes: 1: Iterator 2: Type Enumerator 3: Subtype Enumerator.
-* The predefined keywords shall be used for the corresponding asset parts and can be found in the according subchapters.
+* The predefined keywords shall be used for the corresponding asset parts and can be found in the corresponding subchapters.
 
 === Metadata
 
-* Naming of fields shall be according to lowerCamelCase definition, starting with lower letters.
+The following rules for metadata apply:
+
+* Fields shall be named according to the lowerCamelCase definition, starting with lowercase letters.
 * Naming of custom properties shall follow the predefined keys.
-* Objects, arrays (lists) and enums shall follow the .json notation.
+* Objects, arrays (lists), and enums shall follow the notation in the corresponding json files.
 
 == _3D asset_ file
 
 The _3D asset_ file provides metadata as well as a mapping table to {THIS_STANDARD} _material property_ files.
-This information extends the geometry of an asset given in standard _3D model_ file formats, for example, glTF, FBX or USD.
+This information extends the geometry of an asset given in standard _3D model_ file formats, for example, glTF, FBX, or USD.
 The _3D asset_ file is in JSON format with the file extension `xoma`.
 As indicated above, the asset file has to have the same file name as the accompanying _3D model_.
-This is an example of a _3D model_ file in glTF format with an accompanying _3D asset_ file:
+The following is an example of a _3D model_ file in glTF format with an accompanying _3D asset_ file:
 
 * `my-model.gltf`
 * `my-model.xoma`
 
 == Requirements
 
-* The object's geometry shall be in real word scale, using meters as unit for measurement for distances.
-* The object's origins and pivot points shall coincide with position and orientation of the origin of the object's reference coordinate frame if not specified otherwise.
+* The geometry of the object shall be in real-word scale, using meters as the unit for measurement distances.
+* The object's origins and pivot points shall coincide with position and orientation of the origin of the object's reference coordinate frame, unless otherwise specified .
 * Meshes shall not contain problematic characteristics such as doubled, isolated, coincident, coplanar, degenerate, or primitives.
 * Meshes shall have outside facing normals. Soft or hard edges shall be set correctly.
-* Meshes shall not be empty, nor contain multiple LODs.
-* Meshes shall be triangulated and potential normal maps shall match that triangulation.
-* Rendering materials shall support PBR workflows and there shall not be geometry without assigned material.
-* Additional requirements apply, when {THIS_STANDARD} assignment textures are used:
+* Meshes shall not be empty or contain multiple LODs.
+* Meshes shall be triangulated. Potential normal maps shall match that triangulation.
+* Rendering materials shall support physically based rendering (PBR) workflows and there shall not be geometry without assigned material.
+* Additional requirements apply when {THIS_STANDARD} assignment textures are used:
 ** UV channel 1 shall be used for assignment textures.
-** UV Islands shall have margins inbetween, so that assignment texture interpolation errors are avoided.
+** UV Islands shall have margins in between, so that assignment texture interpolation errors are avoided.
 ** There shall not be any geometry without UV coverage.
 
 
 == Recommendations
+
 * UVs should not overlap and be within 0-1 UV space.
 * Elongated primitives should be avoided as they fit badly in acceleration structures.
 * Alpha-textured meshes should be optimized to minimize the amount of alpha testing.
 * Meshes should not have holes or gaps.
-* Meshes should have clean edgeflow.
+* Meshes should have a clean edgeflow.
 * Usage of N-Gons is not recommended.
 * Faces should be one-sided.
-* The lowest number of polygons possible should be strived for while still retaining the object’s shape.
+* An object's shape should have the lowest possible number of polygons.
 * Texel density should be homogeneous and as low as possible.
 * UV stretching should be minimized.
-* Naming of files, nodes, meshes and materials should be meaningful.
-* Usage of multiple PBR maps is encouraged (albedo, roughness, metallic, normals).
+* Naming of files, nodes, meshes, and materials should be meaningful.
+* Usage of multiple PBR maps is encouraged (for example, albedo, roughness, metallic, normals).
 * Smaller objects should have one _material_ per object (for example, baked traffic cone), while larger objects should contain multiple seamless repeatable materials (for example, brick building).