Skip to content

Commit a877414

Browse files
lilleyselilleyse
authored
Merge pull request #69 from CesiumGS/ext-primitive-voxels-revisions
Revise `EXT_primitive_voxels`
2 parents 91fc2f8 + 519ff87 commit a877414

22 files changed

+554
-78
lines changed

‎.github/workflows/CI.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ jobs:
2323

2424
steps:
2525
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
26-
- uses: actions/checkout@v2
26+
- uses: actions/checkout@v4
2727

2828
# Build spec targets
2929
- name: spec-generate
@@ -32,7 +32,7 @@ jobs:
3232
make Specification.html Specification.pdf
3333
3434
- name: Archive generated files
35-
uses: actions/upload-artifact@v2
35+
uses: actions/upload-artifact@v4
3636
with:
3737
name: spec-outputs
3838
path: |

‎extensions/2.0/Vendor/EXT_implicit_cylinder_region/README.md

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# EXT_implicit_cylinder_region
2+
3+
## Contributors
4+
5+
- Janine Liu, Cesium
6+
- Sean Lilley, Cesium
7+
8+
## Status
9+
10+
Draft
11+
12+
## Dependencies
13+
14+
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.
15+
16+
## Overview
17+
18+
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.
19+
20+
`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.
21+
22+
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.
23+
24+
### Details
25+
26+
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.
27+
28+
<table>
29+
<tr>
30+
<th>
31+
Example
32+
</th>
33+
</tr>
34+
<tr>
35+
<td>
36+
37+
```json
38+
"extensions": [
39+
{
40+
"KHR_implicit_shapes": {
41+
"shapes": [
42+
{
43+
"type": "cylinder region",
44+
"extensions": {
45+
"EXT_implicit_cylinder_region": {
46+
"minRadius": 0.5,
47+
"maxRadius": 1,
48+
"height": 2
49+
}
50+
}
51+
}
52+
]
53+
}
54+
}
55+
]
56+
```
57+
58+
</td>
59+
<td>
60+
<img src="figures/hollow-cylinder.png">
61+
</td>
62+
</tr>
63+
</table>
64+
65+
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.
66+
67+
Angles are given in radians within the range `[-pi, pi]` and open clockwise around the cylinder (see figure below).
68+
69+
![](figures/cylinder-angle.png)
70+
71+
<table>
72+
<tr>
73+
<th>
74+
Example
75+
</th>
76+
</tr>
77+
<tr>
78+
<td>
79+
80+
```json
81+
"extensions": [
82+
{
83+
"KHR_implicit_shapes": {
84+
"shapes": [
85+
{
86+
"type": "cylinder region",
87+
"extensions": {
88+
"EXT_implicit_cylinder_region": {
89+
"minRadius": 0.5,
90+
"maxRadius": 1,
91+
"height": 2,
92+
"minAngle": 0,
93+
"maxAngle": 3.1415
94+
}
95+
}
96+
}
97+
]
98+
}
99+
}
100+
]
101+
```
102+
</td>
103+
<td>
104+
<img src="figures/half-cylinder.png">
105+
</td>
106+
</tr>
107+
</table>
108+
109+
## Optional vs. Required
110+
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/figures/cylinder-angle.png

29.7 KB
Loading

‎extensions/2.0/Vendor/EXT_implicit_cylinder_region/figures/half-cylinder.png

9.27 KB
Loading

‎extensions/2.0/Vendor/EXT_implicit_cylinder_region/figures/hollow-cylinder.png

14.8 KB
Loading

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

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "glTF.KHR_implicit_shapes.shape.EXT_implicit_cylinder_region.schema.json",
4+
"title": "EXT_implicit_cylinder_region extension on KHR_implicit_shapes.shape",
5+
"type": "object",
6+
"description": "Extension of `KHR_implicit_shapes.shape` to represent an implicit cylinder region in a glTF model.",
7+
"allOf": [
8+
{
9+
"$ref": "glTFProperty.schema.json"
10+
}
11+
],
12+
"properties": {
13+
"minRadius": {
14+
"type": "number",
15+
"description": "The inner radius of the cylinder region along the X and Z axes, in meters.",
16+
"minimum": 0
17+
},
18+
"maxRadius": {
19+
"type": "number",
20+
"description": "The outer radius of the cylinder region along the X and Z axes, in meters.",
21+
"minimum": 0
22+
},
23+
"height": {
24+
"type": "number",
25+
"description": "The height of the cylinder in meters along the Y-axis, in meters.",
26+
"minimum": 0
27+
},
28+
"minAngle": {
29+
"type": "number",
30+
"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].",
31+
"minimum": -3.14159265359,
32+
"maximum": 3.14159265359,
33+
"default": -3.14159265359
34+
},
35+
"maxAngle": {
36+
"type": "number",
37+
"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].",
38+
"minimum": -3.14159265359,
39+
"maximum": 3.14159265359,
40+
"default": 3.14159265359
41+
}
42+
},
43+
"required": [
44+
"minRadius",
45+
"maxRadius",
46+
"height"
47+
]
48+
}

‎extensions/2.0/Vendor/EXT_implicit_ellipsoid_region/README.md

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# EXT_implicit_ellipsoid_region
2+
3+
## Contributors
4+
5+
- Janine Liu, Cesium
6+
- Sean Lilley, Cesium
7+
8+
## Status
9+
10+
Draft
11+
12+
## Dependencies
13+
14+
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.
15+
16+
## Overview
17+
18+
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.
19+
20+
`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.
21+
22+
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.
23+
24+
### Details
25+
26+
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.
27+
28+
> The `x` and `z` radii are made equal to simplify the math required to render implicit regions along the ellipsoid.
29+
30+
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.
31+
32+
This example corresponds to the image below it:
33+
34+
```json
35+
"extensions": [
36+
{
37+
"KHR_implicit_shapes": {
38+
"shapes": [
39+
{
40+
"type": "ellipsoid region",
41+
"extensions": {
42+
"EXT_implicit_ellipsoid_region": {
43+
"semiMajorAxisRadius": 3.5,
44+
"semiMinorAxisRadius": 2,
45+
"minHeight": 0,
46+
"maxHeight": 0.5
47+
}
48+
}
49+
}
50+
]
51+
}
52+
}
53+
]
54+
```
55+
56+
![](figures/hollow-ellipsoid.png)
57+
58+
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]`.
59+
60+
```json
61+
"extensions": [
62+
{
63+
"KHR_implicit_shapes": {
64+
"shapes": [
65+
{
66+
"type": "ellipsoid region",
67+
"extensions": {
68+
"EXT_implicit_ellipsoid_region": {
69+
"semiMajorAxisRadius": 3.5,
70+
"semiMinorAxisRadius": 2,
71+
"minHeight": 0,
72+
"maxHeight": 0.5,
73+
"minLongitude": 0,
74+
"maxLongitude": 1.57079632679,
75+
"minLatitude": -0.78539816339,
76+
"maxLatitude": 0.78539816339,
77+
}
78+
}
79+
}
80+
]
81+
}
82+
}
83+
]
84+
```
85+
86+
![](figures/half-ellipsoid.png)
87+
88+
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.
89+
90+
## Optional vs. Required
91+
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/figures/half-ellipsoid.png

29.9 KB
Loading

‎extensions/2.0/Vendor/EXT_implicit_ellipsoid_region/figures/hollow-ellipsoid.png

33.1 KB
Loading

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

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "glTF.KHR_implicit_shapes.shape.EXT_implicit_ellipsoid_region.schema.json",
4+
"title": "EXT_implicit_ellipsoid_region extension on KHR_implicit_shapes.shape",
5+
"type": "object",
6+
"description": "Extension of `KHR_implicit_shapes.shape` to represent an implicit ellipsoid region in a glTF model.",
7+
"allOf": [
8+
{
9+
"$ref": "glTFProperty.schema.json"
10+
}
11+
],
12+
"properties": {
13+
"semiMajorAxisRadius": {
14+
"type": "number",
15+
"description": "The radius along the semi-major axis of the reference ellipsoid in meters. Corresponds to the radii along the X and Z axes.",
16+
"minimum": 0
17+
},
18+
"semiMinorAxisRadius": {
19+
"type": "number",
20+
"description": "The radius along the semi-minor axis of the reference ellipsoid in meters. Corresponds to the radius along the Y-axis.",
21+
"minimum": 0
22+
},
23+
"minHeight": {
24+
"type": "number",
25+
"description": "The minimum height of the region relative to the ellipsoid's surface, in meters. May be negative."
26+
},
27+
"maxHeight": {
28+
"type": "number",
29+
"description": "The maximum height of the region relative to the ellipsoid's surface, in meters. May be negative."
30+
},
31+
"minLatitude": {
32+
"type": "number",
33+
"description": "The minimum latitude (a.k.a. polar angle) of the region, in radians. Must be in the range [-pi/2, pi/2].",
34+
"minimum": -1.57079632679,
35+
"maximum": 1.57079632679,
36+
"default": -1.57079632679
37+
},
38+
"maxLatitude": {
39+
"type": "number",
40+
"description": "The maximum latitude (a.k.a. polar angle) of the region, in radians. Must be in the range [-pi/2, pi/2].",
41+
"minimum": -1.57079632679,
42+
"maximum": 1.57079632679,
43+
"default": 1.57079632679
44+
},
45+
"minLongitude": {
46+
"type": "number",
47+
"description": "The minimum longitude (a.k.a. azimuthal angle) of the region, in radians. Must be in the range [-pi, pi].",
48+
"minimum": -3.14159265359,
49+
"maximum": 3.14159265359,
50+
"default": -3.14159265359
51+
},
52+
"maxLongitude": {
53+
"type": "number",
54+
"description": "The maximum longitude (a.k.a. azimuthal angle) of the region, in radians. Must be in the range [-pi, pi].",
55+
"minimum": -3.14159265359,
56+
"maximum": 3.14159265359,
57+
"default": 3.14159265359
58+
}
59+
},
60+
"required": [
61+
"semiMajorAxisRadius",
62+
"semiMinorAxisRadius",
63+
"minHeight",
64+
"maxHeight"
65+
]
66+
}

0 commit comments

Comments
 (0)