Merge pull request #69 from CesiumGS/ext-primitive-voxels-revisions

Revise `EXT_primitive_voxels`

.github/workflows/CI.yml

@@ -23,7 +23,7 @@ jobs:
 
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
       # Build spec targets
       - name: spec-generate
@@ -32,7 +32,7 @@ jobs:
           make Specification.html Specification.pdf
 
       - name: Archive generated files
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: spec-outputs
           path: |

extensions/2.0/Vendor/EXT_implicit_cylinder_region/README.md

@@ -0,0 +1,110 @@
+# EXT_implicit_cylinder_region
+
+## Contributors
+
+- Janine Liu, Cesium
+- Sean Lilley, Cesium
+
+## Status
+
+Draft
+
+## Dependencies
+
+Written against the glTF 2.0 specification. Depends on the [`KHR_implicit_shapes`](https://github.com/eoineoineoin/glTF/tree/refs/heads/collisionShapeMerge/extensions/2.0/Khronos/KHR_implicit_shapes) extension.
+
+## Overview
+
+This extension defines a cylinder-conforming region as an additional shape type for the `KHR_implicit_shapes` extension. These regions are useful for visualizing real-world data that has been captured by cylindrical sensors.
+
+`EXT_implicit_cylinder_region` extends the `shape` object in `KHR_implicit_shapes`. The `shape.type` should be set to `"cylinder region"`. The properties define a region following the surface of a cylinder between two different radius values.
+
+The cylinder does not need to be completely represented by the volume—for instance, the region may be hollow inside like a tube. However, an inner radius of `0` results in a completely solid cylinder.
+
+### Details
+
+The cylinder is centered at the origin, where the radius is measured along the `x` and `z` axes. The `height` of the cylinder is aligned with the `y` axis.
+
+<table>
+  <tr>
+    <th>
+    Example
+    </th>
+  </tr>
+  <tr>
+    <td>
+
+```json
+"extensions": [
+  {
+    "KHR_implicit_shapes": {
+      "shapes": [
+        {
+          "type": "cylinder region",
+          "extensions": {
+            "EXT_implicit_cylinder_region": {
+              "minRadius": 0.5,
+              "maxRadius": 1,
+              "height": 2
+            }
+          }
+        }
+      ]
+    }
+  }
+]
+```
+
+  </td>
+    <td>
+    <img src="figures/hollow-cylinder.png">
+    </td>
+  </tr>
+</table>
+
+A cylinder region may also be confined to a certain angular range. The `minAngle` and `maxAngle` properties define the angles at which the region starts and stops on the cylinder.
+
+Angles are given in radians within the range `[-pi, pi]` and open clockwise around the cylinder (see figure below).
+
+![](figures/cylinder-angle.png)
+
+<table>
+  <tr>
+    <th>
+    Example
+    </th>
+  </tr>
+  <tr>
+    <td>
+
+```json
+"extensions": [
+  {
+    "KHR_implicit_shapes": {
+      "shapes": [
+        {
+          "type": "cylinder region",
+          "extensions": {
+            "EXT_implicit_cylinder_region": {
+              "minRadius": 0.5,
+              "maxRadius": 1,
+              "height": 2,
+              "minAngle": 0,
+              "maxAngle": 3.1415
+            }
+          }
+        }
+      ]
+    }
+  }
+]
+```
+</td>
+    <td>
+    <img src="figures/half-cylinder.png">
+    </td>
+  </tr>
+</table>
+
+## Optional vs. Required
+This extension is required, meaning it should be placed in both the `extensionsUsed` list and `extensionsRequired` list.

extensions/2.0/Vendor/EXT_implicit_cylinder_region/schema/glTF.KHR_implicit_shapes.shape.EXT_implicit_cylinder_region.schema.json

@@ -0,0 +1,48 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "glTF.KHR_implicit_shapes.shape.EXT_implicit_cylinder_region.schema.json",
+    "title": "EXT_implicit_cylinder_region extension on KHR_implicit_shapes.shape",
+    "type": "object",
+    "description": "Extension of `KHR_implicit_shapes.shape` to represent an implicit cylinder region in a glTF model.",
+    "allOf": [
+        {
+            "$ref": "glTFProperty.schema.json"
+        }
+    ],
+    "properties": {
+        "minRadius": {
+            "type": "number",
+            "description": "The inner radius of the cylinder region along the X and Z axes, in meters.",
+            "minimum": 0
+        },
+        "maxRadius": {
+            "type": "number",
+            "description": "The outer radius of the cylinder region along the X and Z axes, in meters.",
+            "minimum": 0
+        },
+        "height": {
+            "type": "number",
+            "description": "The height of the cylinder in meters along the Y-axis, in meters.",
+            "minimum": 0
+        },
+        "minAngle": {
+            "type": "number",
+            "description": "The minimum angle of the cylinder region in radians. In other words, this is the angle where the cylinder region starts. Must be in the range [-pi, pi].",
+            "minimum": -3.14159265359,
+            "maximum": 3.14159265359,
+            "default": -3.14159265359
+        },
+        "maxAngle": {
+            "type": "number",
+            "description": "The maximum angle of the cylinder region in radians. In other words, this is the angle where the cylinder region ends. Must be in the range [-pi, pi].",
+            "minimum": -3.14159265359,
+            "maximum": 3.14159265359,
+            "default": 3.14159265359
+        }
+    },
+    "required": [
+        "minRadius",
+        "maxRadius",
+        "height"
+    ]
+}

extensions/2.0/Vendor/EXT_implicit_ellipsoid_region/README.md

@@ -0,0 +1,91 @@
+# EXT_implicit_ellipsoid_region
+
+## Contributors
+
+- Janine Liu, Cesium
+- Sean Lilley, Cesium
+
+## Status
+
+Draft
+
+## Dependencies
+
+Written against the glTF 2.0 specification. Depends on the [`KHR_implicit_shapes`](https://github.com/eoineoineoin/glTF/tree/refs/heads/collisionShapeMerge/extensions/2.0/Khronos/KHR_implicit_shapes) extension.
+
+## Overview
+
+This extension defines an ellipsoid-conforming region as an additional shape type for the `KHR_implicit_shapes` extension. These regions are commonly used in geospatial applications to describe volumes that conform to the curvature of the Earth, or other bodies.
+
+`EXT_implicit_ellipsoid_region` extends the `shape` object in `KHR_implicit_shapes`. The `shape.type` should be set to `"ellipsoid region"`. The properties define the region following the surface of the ellipsoid between two different height values.
+
+The volume does not necessarily contain the full ellipsoid—and for many geospatial use cases, it will not. Rather, the ellipsoid is used as a reference from which the actual region is extruded. However, a region may be extend beneath the surface of the ellipsoid. Given the right height values, the region could contain the entire ellipsoid if desired.
+
+### Details
+
+The reference ellipsoid is centered at the origin. The `semiMajorAxisRadius` indicates the radius of the ellipsoid in meters along the `x` and `z` axes. The `semiMinorAxisRadius` indicates the radius of the ellipsoid in meters along the `y` axis.
+
+> The `x` and `z` radii are made equal to simplify the math required to render implicit regions along the ellipsoid.
+
+The `minHeight` and `maxHeight` properties indicate the heights of the region from the ellipsoid's surface in meters. A height of `0` sits right at the surface. Negative heights are also valid—they simply extend underneath the ellipsoid's surface.
+
+This example corresponds to the image below it:
+
+```json
+"extensions": [
+  {
+    "KHR_implicit_shapes": {
+      "shapes": [
+        {
+          "type": "ellipsoid region",
+          "extensions": {
+            "EXT_implicit_ellipsoid_region": {
+              "semiMajorAxisRadius": 3.5,
+              "semiMinorAxisRadius": 2,
+              "minHeight": 0,
+              "maxHeight": 0.5
+            }
+          }
+        }
+      ]
+    }
+  }
+]
+```
+
+![](figures/hollow-ellipsoid.png)
+
+An ellipsoid region may also be confined to a specific latitude and/or longitude range. The `minLatitude` and `maxLatitude` properties represent the latitude values at which the region starts and stops, defined in the range `[-pi/2, pi/2]`. Similarly, the `minLongitude` and `maxLongitude` properties represent the longitude bounds within the range `[-pi, pi]`.
+
+```json
+"extensions": [
+  {
+    "KHR_implicit_shapes": {
+      "shapes": [
+        {
+          "type": "ellipsoid region",
+          "extensions": {
+            "EXT_implicit_ellipsoid_region": {
+              "semiMajorAxisRadius": 3.5,
+              "semiMinorAxisRadius": 2,
+              "minHeight": 0,
+              "maxHeight": 0.5,
+              "minLongitude": 0,
+              "maxLongitude": 1.57079632679,
+              "minLatitude": -0.78539816339,
+              "maxLatitude": 0.78539816339,
+            }
+          }
+        }
+      ]
+    }
+  }
+]
+```
+
+![](figures/half-ellipsoid.png)
+
+It is valid for the `maxLongitude` property to be less than `minLongitude`. This would define a region that crosses over the line at `-pi` or `pi`, equivalent to the International Date Line on Earth.
+
+## Optional vs. Required
+This extension is required, meaning it should be placed in both the `extensionsUsed` list and `extensionsRequired` list.

extensions/2.0/Vendor/EXT_implicit_ellipsoid_region/schema/glTF.KHR_implicit_shapes.shape.EXT_implicit_ellipsoid_region.schema.json

@@ -0,0 +1,66 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "glTF.KHR_implicit_shapes.shape.EXT_implicit_ellipsoid_region.schema.json",
+    "title": "EXT_implicit_ellipsoid_region extension on KHR_implicit_shapes.shape",
+    "type": "object",
+    "description": "Extension of `KHR_implicit_shapes.shape` to represent an implicit ellipsoid region in a glTF model.",
+    "allOf": [
+        {
+            "$ref": "glTFProperty.schema.json"
+        }
+    ],
+    "properties": {
+        "semiMajorAxisRadius": {
+            "type": "number",
+            "description": "The radius along the semi-major axis of the reference ellipsoid in meters. Corresponds to the radii along the X and Z axes.",
+            "minimum": 0
+        },
+        "semiMinorAxisRadius": {
+            "type": "number",
+            "description": "The radius along the semi-minor axis of the reference ellipsoid in meters. Corresponds to the radius along the Y-axis.",
+            "minimum": 0
+        },
+        "minHeight": {
+            "type": "number",
+            "description": "The minimum height of the region relative to the ellipsoid's surface, in meters. May be negative."
+        },
+        "maxHeight": {
+            "type": "number",
+            "description": "The maximum height of the region relative to the ellipsoid's surface, in meters. May be negative."
+        },
+        "minLatitude": {
+            "type": "number",
+            "description": "The minimum latitude (a.k.a. polar angle) of the region, in radians. Must be in the range [-pi/2, pi/2].",
+            "minimum": -1.57079632679,
+            "maximum": 1.57079632679,
+            "default": -1.57079632679
+        },
+        "maxLatitude": {
+            "type": "number",
+            "description": "The maximum latitude (a.k.a. polar angle) of the region, in radians. Must be in the range [-pi/2, pi/2].",
+            "minimum": -1.57079632679,
+            "maximum": 1.57079632679,
+            "default": 1.57079632679
+        },
+        "minLongitude": {
+            "type": "number",
+            "description": "The minimum longitude (a.k.a. azimuthal angle) of the region, in radians. Must be in the range [-pi, pi].",
+            "minimum": -3.14159265359,
+            "maximum": 3.14159265359,
+            "default": -3.14159265359
+        },
+        "maxLongitude": {
+            "type": "number",
+            "description": "The maximum longitude (a.k.a. azimuthal angle) of the region, in radians. Must be in the range [-pi, pi].",
+            "minimum": -3.14159265359,
+            "maximum": 3.14159265359,
+            "default": 3.14159265359
+        }
+    },
+    "required": [
+        "semiMajorAxisRadius",
+        "semiMinorAxisRadius",
+        "minHeight",
+        "maxHeight"
+    ]
+}