Autumn NIAC 2024 edits

atomprobe-tc · atomprobe-tc · commit 9493eb5335bc · 2025-01-10T17:18:59.000+01:00
diff --git a/base_classes/NXcg_alpha_complex.nxdl.xml b/base_classes/NXcg_alpha_complex.nxdl.xml
@@ -23,100 +23,79 @@
 -->
 <!--
 The so-called spectrum or sets of (weighted) alpha shapes includes the convex hull of a point set.-->
-<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXcg_alpha_complex" extends="NXcg_primitive_set" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXcg_alpha_complex" extends="NXcg_primitive" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
     <doc>
-         Computational geometry of alpha shapes or alpha wrappings about primitives.
+         Computational geometry of alpha complexes (alpha shapes or alpha wrappings) about primitives.
          
          For details see:
          
          * https://dx.doi.org/10.1109/TIT.1983.1056714 for 2D,
          * https://dx.doi.org/10.1145/174462.156635 for 3D,
          * https://dl.acm.org/doi/10.5555/871114 for weighted, and
-         * https://doc.cgal.org/latest/Alpha_shapes_3 for 3D implementation
-         * https://doc.cgal.org/latest/Manual/packages.html#PkgAlphaWrap3 for 3D wrappings
+         * https://doc.cgal.org/latest/Alpha_shapes_3 for 3D implementation of alpha shapes, and
+         * https://doc.cgal.org/latest/Manual/packages.html#PkgAlphaWrap3 for 3D alpha wrappings
          
-         in CGAL, the Computational Geometry Algorithms Library.
+         in CGAL, the Computational Geometry Algorithms Library respectively.
          As a starting point, we follow the conventions of the CGAL library.
+         
+         In general, an alpha complex is a not necessarily connected or not necessarily pure complex,
+         i.e. singular faces may exist. The number of cells, faces, and edges depends on how a specific
+         alpha complex is filtered for lower-dimensional simplices. The fields is_regularized and
+         regularization can be used to provide details about regularization procedures.
     </doc>
     <field name="type">
         <doc>
              Type of alpha complex following the terminology used by CGAL for now.
              
-             Basic means (unweighted) alpha shapes. Alpha_wrapping means meshes
-             created using the alpha_wrapping algorithm.
+             Alpha_shape means meshes created using one of the alpha_shape algorithm.
+             Alpha_wrapping means meshes created using the alpha_wrapping algorithm.
         </doc>
         <enumeration>
             <item value="convex_hull"/>
             <item value="alpha_shape"/>
             <item value="alpha_wrapping"/>
         </enumeration>
     </field>
-    <field name="regularize_alpha_complex" type="NX_BOOLEAN">
+    <field name="regularization">
         <doc>
-             Are singular faces removed, i.e. has the alpha complex
-             been regularized or not.
+             Human-readable description about regularization procedures.
+        </doc>
+    </field>
+    <field name="is_regularized" type="NX_BOOLEAN">
+        <doc>
+             Was the alpha complex regularized, i.e. have singular faces been removed, or not.
         </doc>
     </field>
-    <!--R+0 means positive real number including zero which is a super set of NX_FLOAT and a sub-set of NX_NUMBER-->
     <field name="alpha" type="NX_NUMBER" units="NX_LENGTH">
         <doc>
              The alpha parameter, i.e. the radius of the alpha-sphere that
              is used when computing the alpha complex.
         </doc>
     </field>
-    <!--the dim: argument can be omitted to indicate that a scalar is expected
-means a length quantity, i.e. m, km, or nm is possible i.e. has to be length but no further constraints
-stating meter is a stronger constraint while m is the strongest constraint, meaning literally the value is m.-->
     <field name="offset" type="NX_NUMBER" units="NX_LENGTH">
         <doc>
              The offset distance parameter used when computing alpha_wrappings.
         </doc>
     </field>
     <!--check again carefully the CGAL documentation talks about, for 3D, the square of the radius!-->
-    <group name="point_setID" type="NXcg_point_set">
-        <!--
-basically just constraints that if you use one or more instances of NXcg_point_set
-inside an instance of NXcg_alpha_complex, name that group with the prefix "point_set"
--->
+    <group name="point_cloudID" type="NXcg_point" nameType="partial">
         <doc>
-             Point cloud for which the alpha shape or wrapping has been computed.
+             Point cloud serving as input for the computation of the alpha complex.
         </doc>
     </group>
-    <!--this could also just be implemented as a link but how would this be possible
-unfold the NXcg_point_set and add a
-weight(NX_NUMBER):
-doc: Weights for each point
-In general, an alpha complex is a disconnected and non-pure complex,
-meaning in particular that the alpha complex may have singular faces.
-so the number of cells, faces and edges depends on how a specific alpha complex,
-i.e. an alpha-shape of S for alpha, is filtrated with respect to k < d-dimensional
-simplices. Here we assume that number_of_cells, number_of_faces, number_of_edges
-are reported assuming one filtrates these simplices according to type.
-also using the assumption the base class reports the unique vertices
-of the specifically filtrated alpha complex.-->
-    <group name="triangle_setID" type="NXcg_triangle_set">
+    <group name="triangle_soupID" type="NXcg_triangle" nameType="partial">
         <doc>
-             Triangle soup for which the alpha wrapping has been computed.
+             Triangle soup serving as input for the computation of the alpha complex.
         </doc>
     </group>
-    <group name="triangle_meshID" type="NXcg_triangle_set">
+    <group name="alpha_complexID" type="NXcg_triangle" nameType="partial">
         <doc>
-             Triangle mesh representing the alpha complex.
+             Triangle mesh representing the output of the computation, i.e. the alpha complex.
         </doc>
     </group>
-    <!--add for each triangle if desirable a notation of whether the simplex is
-exterior, regular, singular, or interior with respect to the alpha complex
-a triangulation is more than a triangle (soup)/set because there it has connectivity
-customize the NXcg_triangle_set base class members such that connectivity can be contained naturally
-we need to find also a better name for this, what people intutive understand
-as the interior, may not even exist for a given alpha value
-more specifically it is the set of filtrated cells acknowledging mode
-e.g. the interior cells of the regularized alpha complex-->
-    <group name="interior_cellsID" type="NXcg_tetrahedron_set">
+    <group name="tetrahedralizationID" type="NXcg_tetrahedron" nameType="partial">
         <doc>
-             Set of tetrahedra representing the volume inside the alpha complex.
+             Tetrahedra representing an interior volume of the alpha complex (if such exists).
         </doc>
     </group>
-    <!--document the alpha status
-https://doc.cgal.org/latest/Alpha_shapes_3/classCGAL_1_1Alpha__status.html-->
 </definition>
diff --git a/base_classes/NXcg_cylinder.nxdl.xml b/base_classes/NXcg_cylinder.nxdl.xml
@@ -24,7 +24,7 @@
 <!--
 redundant as there is NXcsg, NXquadric, NXsolid_geometry with which
 cylinder could be constructed, but NXcylinder is easier to understand-->
-<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXcg_cylinder_set" extends="NXcg_primitive_set" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXcg_cylinder" extends="NXcg_primitive" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
     <symbols>
         <doc>
              The symbols used in the schema to specify e.g. dimensions of arrays.
@@ -41,33 +41,25 @@ cylinder could be constructed, but NXcylinder is easier to understand-->
         </symbol>
     </symbols>
     <doc>
-         Computational geometry description of a set of cylinders.
+         Computational geometry description of a set of cylinders or (truncated) cones.
          
          The radius can either be defined in the radii field or by filling both
          the upper_cap_radii or lower_cap_radii field. The latter field case can
-         thus be used to represent truncated cones.
+         thus be used to represent (truncated) cones.
     </doc>
     <field name="height" type="NX_NUMBER" units="NX_LENGTH">
         <doc>
              A direction vector which is parallel to the cylinder/cone axis
              and whose magnitude is the height of the cylinder/cone.
+             
+             The upper_cap is defined as the one that is farther away to the origin
+             when inspecting a parallel projection onto the direction vector.
         </doc>
         <dimensions rank="2">
             <dim index="1" value="c"/>
             <dim index="2" value="d"/>
         </dimensions>
     </field>
-    <!--observe that although we claim that d is the dimensionality we have
-currently no strategy to tell it must not be d but the actual value
-equally so the symbol c, currently all we say that in the specialization
-defined here the fields radii, upper_cap_radius, and others are all having
-value arguments of the same shape, i.e. these are arrays of rank one with some length c!
-behind the dimensionality field defined either in the here defined specialization
-of NXcg_primitive_set or otherwise that variable is undefined
-alternatively one could store the center of the lower and upper cap but
-these are then no longer necessarily on the same axis
-maybe a future feature for representing skewed cylinder, but then
-one should really better use NXquadric...-->
     <field name="radius" type="NX_NUMBER" units="NX_LENGTH">
         <doc>
              Radius of the cylinder if all have the same radius.
@@ -106,7 +98,7 @@ one should really better use NXquadric...-->
     <!--properties of the cylinder-->
     <field name="lateral_surface_area" type="NX_NUMBER" units="NX_AREA">
         <doc>
-             Lateral surface area
+             Lateral surface area of each cylinder.
         </doc>
         <dimensions rank="1">
             <dim index="1" value="c"/>
@@ -130,16 +122,10 @@ one should really better use NXquadric...-->
     </field>
     <field name="total_surface_area" type="NX_NUMBER" units="NX_AREA">
         <doc>
-             Sum of upper and lower cap areas and lateral surface area
-             of each cylinder.
+             Sum of upper and lower cap area and lateral surface area of each cylinder.
         </doc>
         <dimensions rank="1">
             <dim index="1" value="c"/>
         </dimensions>
     </field>
-    <!--again cap, lateral surface area and volume are so trivial to compute
-do we need really storage for this or recompute on-the-fly?
-similarly to hollow sphere discussion, hollow cylinder, cylinder stack
-do wish to define intersections?, if this is the case, one
-should use the NXcsg and NXquadric descriptions?-->
 </definition>
diff --git a/base_classes/NXcg_ellipsoid.nxdl.xml b/base_classes/NXcg_ellipsoid.nxdl.xml
@@ -23,7 +23,7 @@
 -->
 <!--
 redundant as there is NXcsg, and NXquadric but easier to understand-->
-<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXcg_ellipsoid_set" extends="NXcg_primitive_set" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXcg_ellipsoid" extends="NXcg_primitive" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
     <symbols>
         <doc>
              The symbols used in the schema to specify e.g. dimensions of arrays.
@@ -61,5 +61,20 @@ redundant as there is NXcsg, and NXquadric but easier to understand-->
             <dim index="2" value="d"/>
         </dimensions>
     </field>
+    <!--convenience dictionary entries when all ellipsoids in the set are spheres.-->
+    <field name="radius" type="NX_NUMBER" units="NX_LENGTH">
+        <doc>
+             In the case that all ellipsoids are spheres.
+        </doc>
+    </field>
+    <field name="radii" type="NX_NUMBER" units="NX_LENGTH">
+        <doc>
+             In the case that all ellipsoids are spheres whose radii differ.
+             For a mixture of spheres use half_axes_radii.
+        </doc>
+        <dimensions rank="1">
+            <dim index="1" value="c"/>
+        </dimensions>
+    </field>
     <!--properties of ellipsoids-->
 </definition>
diff --git a/base_classes/NXcg_face_list_data_structure.nxdl.xml b/base_classes/NXcg_face_list_data_structure.nxdl.xml
@@ -23,7 +23,7 @@
 -->
 <!--
 duplicate of an NXoff_geometry ?-->
-<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXcg_face_list_data_structure" extends="NXcg_primitive_set" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXcg_face_list_data_structure" extends="NXcg_primitive" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
     <symbols>
         <doc>
              The symbols used in the schema to specify e.g. dimensions of arrays.
@@ -62,18 +62,17 @@ duplicate of an NXoff_geometry ?-->
     <doc>
          Computational geometry of primitives via a face-and-edge-list data structure.
          
-         Primitives must neither be degenerated nor self-intersect but can differ in
-         their properties. A face-and-edge-list-based description of primitives is
+         Primitives must neither be degenerated nor self-intersect but can have different
+         properties. A face-and-edge-list-based description of primitives is
          frequently used for triangles and polyhedra to store them on disk for
          visualization purposes (see OFF, PLY, VTK, or STL file formats).
          
-         Although this description is storage efficient it is not well suited for
-         topological analyses though. In this case, scientists may need a different
-         view on the primitives which is better represented with e.g. a
-         half_edge_data_structure.
+         Although this description is storage efficient, it is not well-suited for
+         topological analyses. In this case using a half-edge data structure is
+         an alternative. 
          
          Having an own base class for the data structure how primitives are stored is
-         useful to embrace both users with small or very detailed specification demands.
+         useful to embrace both users with small or detailed specification demands.
     </doc>
     <!--resulting in a design similar to that of NXoff_geometry and the XDMF mixed primitive topology-->
     <field name="number_of_vertices" type="NX_INT" units="NX_UNITLESS">
@@ -159,10 +158,10 @@ duplicate of an NXoff_geometry ?-->
              Positions of the vertices.
              
              Users are encouraged to reduce the vertices to a unique set as this may
-             result in a more efficient storage of the geometry data.
-             It is also possible though to store the vertex positions naively in which
-             case vertices_are_unique is likely False. Naively here means that each
-             vertex is stored even though many share the same positions.
+             result in more efficient storage. Alternatively, storing vertex positions naively
+             should be indicated with setting vertices_are_unique to False.
+             Naively means that each vertex is stored even though many vertices may
+             share the same positions.
         </doc>
         <dimensions rank="2">
             <dim index="1" value="n_v"/>
diff --git a/base_classes/NXcg_half_edge_data_structure.nxdl.xml b/base_classes/NXcg_half_edge_data_structure.nxdl.xml
@@ -21,7 +21,7 @@
 #
 # For further information, see http://www.nexusformat.org
 -->
-<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXcg_half_edge_data_structure" extends="NXobject" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXcg_half_edge_data_structure" extends="NXcg_primitive" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
     <!--holes in the polygon mesh can be handled-->
     <symbols>
         <doc>
@@ -194,8 +194,4 @@
              of microstructural objects like crystals/grains.
         </doc>
     </field>
-    <!--eventually store the Weinberg vector as an integer array
-which could be more efficient
-see https://jerryyin.info/geometry-processing-algorithms/half-edge/
-for an illustrative example of half-edge data structures-->
 </definition>
diff --git a/base_classes/NXcg_primitive.nxdl.xml b/base_classes/NXcg_primitive.nxdl.xml
diff --git a/base_classes/NXcg_sphere.nxdl.xml b/base_classes/NXcg_sphere.nxdl.xml
