add EXT_primitive_voxels #48
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,83 @@ | ||||||
| # EXT_primitive_voxels | ||||||
|
|
||||||
| <p align="center"> | ||||||
| <img src="figures/voxel_cube.png"> | ||||||
| </p> | ||||||
|
|
||||||
| ## Contributors | ||||||
| - Daniel Krupka, Cesium | ||||||
| - Ian Lilley, Cesium | ||||||
| - Sean Lilley, Cesium | ||||||
|
|
||||||
| ## Status | ||||||
| Draft | ||||||
|
|
||||||
| ## Dependencies | ||||||
| Written against the glTF 2.0 specification. | ||||||
|
|
||||||
| ## Overview | ||||||
|
|
||||||
| This extension allows primitives to use their attribute data to represent volumetric (voxel) data. | ||||||
|
|
||||||
| ``` | ||||||
| { | ||||||
| "meshes": [ | ||||||
| { | ||||||
| "primitives": [ | ||||||
| { | ||||||
| "attributes": { | ||||||
| "_TEMPERATURE": 1 | ||||||
| }, | ||||||
| "mode": 2147483648, | ||||||
| "extensions": { | ||||||
| "EXT_primitive_voxels": { | ||||||
| "dimensions": [8, 8, 8], | ||||||
| "bounds": { | ||||||
| "min": [0.25, 0.5, 0.5], | ||||||
| "max": [0.375, 0.625, 0.625] | ||||||
| }, | ||||||
| "padding": { | ||||||
| "before": [1, 1, 1], | ||||||
| "after": [1, 1, 1] | ||||||
| } | ||||||
| } | ||||||
| } | ||||||
| } | ||||||
| ] | ||||||
| } | ||||||
| ] | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| The extension adds three new primitive modes, corresponding to voxel grid geometries: | ||||||
| - `0x80000000` (`2147483648`) - A Cartesian box. The grid is a Cartesian grid of equally-sized boxes. | ||||||
| - `0x80000001` (`2147483649`) - A cylinder. The grid is a stack of concentric rings, evenly divided around the circumference. | ||||||
| - `0x80000002` (`2147483650`) - An ellipsoid. The grid is a set of concentric ellipsoids, divided evenly in latitude and longitude. | ||||||
|
|
||||||
| The lowest byte is reserved for future voxel modes: `0x80000000`-`0x800000FF`. | ||||||
|
|
||||||
| |Box|Cylinder|Ellipsoid| | ||||||
| | ------------- | ------------- | ------------- | | ||||||
| |||| | ||||||
|
|
||||||
| These grids all define "unit" objects centered at the origin, contained in the bounding box between `(-1, -1, -1)` and `(1, 1, 1)`. Node transforms should be used to position, orient, and scale the voxel grid as needed. The `POSITION` attribute is _not_ required or used by this extension - all positioning is through node transforms. | ||||||
|
There was a problem hiding this comment. For the sentence about
The current wording sounds like the former (which I think makes sense), just wanted to check. |
||||||
|
|
||||||
| The `dimensions` property of the extension specifies the voxel grid dimensions: | ||||||
|
There was a problem hiding this comment. There should be a short explanation of how these coordinates map to the memory layout There was a problem hiding this comment. Totally agree, you've described this to me as a "reinterpret cast", but it would be good to describe this in more detail in the spec. There was a problem hiding this comment. Diagrams and pictures could be helpful here, like showing how the same voxel grid maps to these different shapes. |
||||||
| - x/y/z for boxes | ||||||
| - r/z/theta for cylinders | ||||||
|
There was a problem hiding this comment. In glTF, y is up -- is the cylinder z coordinate pointing in the y direction or the z direction? this should be made clear (perhaps with a diagram) There was a problem hiding this comment. I changed the cylinder coordinate names from 👍 to a diagram. |
||||||
| - lon/lat/height for ellipsoids | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| Dimensions must be nonzero. Elements are laid out in memory first-axis-contiguous, e.g. for boxes, `x` data is contiguous (up to stride). | ||||||
|
There was a problem hiding this comment. "first-axis-contiguous" is a term I've never heard before. I find this confusing. I think you mean column major? (albeit that is a confusing term in 3D. here's an example of row major in 3D) basically "x-major" means it's the first index if you access it Also see how NumPy describes its arrays as either row- or column- major (the There was a problem hiding this comment. Perhaps that sentence can be reworded. It's row-major access where x changes the fastest. If this were a C array (row major) it would be accessed like |
||||||
|
|
||||||
| The `bounds` property describes which section of the primitive is mapped to the voxel grid. `bounds.min` and `bounds.max` specify a "rectangular" region of the voxel grid in the appropriate coordinate systems: | ||||||
|
There was a problem hiding this comment. Is bounds used to crop the data or is it used to compress the grid into a smaller region? e.g. if you were to use a sector of a cylinder (let's say a quarter, pi/2 radians), is it using only 1/4th of the grid or is it a sector that's 4 times as detailed? There was a problem hiding this comment. It's compress, not crop. That's a good word, might get the point across better. In you example it would be 1/4th the grid. If you changed the bounds to pi/4 it would be 1/8th the grid, but the same total number of voxels (and thus more detailed). |
||||||
| - Boxes: a rectangular region of the box, between `(-1, -1, -1)` and `(1, 1, 1)`. **This is essentially a no-op - prefer using node transforms for boxes**. | ||||||
|
There was a problem hiding this comment. If it's not going to be used, should it be forbidden for boxes? |
||||||
| - Cylinders: a slice of the cylinder, between `(0, -1, 0)` and `(1, 1, 2*pi)` | ||||||
| - Ellipsoids: a surface patch with height, between `(-pi, -pi/2, 0)` and `(pi, pi/2, 1)` | ||||||
|
|
||||||
| The `padding` property specifies how many rows of attribute data in each dimension come from neighboring grids. This is useful in situations where the primitive represents a single tile in a larger grid, and data from neighboring tiles is needed for non-local effects e.g. trilinear interpolation, blurring, antialiasing. `padding.before` and `padding.after` specify the number of rows before and after the grid in each dimension, e.g. a `padding.before` of 1 and a `padding.after` of 2 in the `y` dimension mean that each series of values in a given `y`-slice is preceded by one value and followed by two. | ||||||
|
There was a problem hiding this comment. To a glTF user (and not a 3D Tiles user), this is going to sound confusing. what is a "tile"? do you have a concrete example to illustrate this? There was a problem hiding this comment. Yeah, I'll need a diagram for this. You're right that calling it a tile is confusing since the padding can be used for other purposes. I'll have to rework this paragraph a bit. There was a problem hiding this comment. wait is it |
||||||
|
|
||||||
| The padding data must be supplied with the rest of the voxel data - this means if `dimensions` is `[d1, d2, d3]`, `beforeCount` is `[b1, b2, b3]`, and `afterCount` is `[a1, a2, a3]`, | ||||||
|
There was a problem hiding this comment. I think I see what you're getting at, but a more concrete example, perhaps with a diagram would be helpful |
||||||
| the attribute must supply `(d1 + a1 + b1)*(d2 + a2 + b2)*(d3 + a3 + b3)` elements. | ||||||
|
|
||||||
| ## Optional vs. Required | ||||||
| This extension is required, meaning it should be placed in both the `extensionsUsed` list and `extensionsRequired` list. | ||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| { | ||
| "$schema": "https://json-schema.org/draft/2020-12/schema", | ||
| "$id": "mesh.primitive.EXT_primitive_voxels.schema.json", | ||
| "title": "EXT_primitive_voxels glTF Mesh Primitive extension", | ||
| "type": "object", | ||
| "description": "`EXT_primitive_voxels` extension for a primitive in a glTF model, to specify voxel grid geomtetry for volumetric data", | ||
| "allOf": [ | ||
| { | ||
| "$ref": "glTFProperty.schema.json" | ||
| } | ||
| ], | ||
| "properties": { | ||
| "dimensions": { | ||
| "type": "array", | ||
| "description": "Dimensions of the voxel grid. x/y/z for a box, r/theta/z for a cylinder, lat/lon/height for an ellipsoid.", | ||
| "items": { | ||
| "type": "integer", | ||
| "minimum": 1 | ||
| }, | ||
| "minItems": 3, | ||
| "maxItems": 3 | ||
| }, | ||
| "bounds": { | ||
| "type": { | ||
| "properties": { | ||
| "minimum": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "number" | ||
| }, | ||
| "minItems": 3, | ||
| "maxItems": 3 | ||
| }, | ||
| "maximum": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "number" | ||
| }, | ||
| "minItems": 3, | ||
| "maxItems": 3 | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "neighboringEdges": { | ||
| "type": { | ||
| "properties": { | ||
| "beforeCount": { | ||
| "type": "array", | ||
| "description": "Number of neighboring data values before each dimension of the grid.", | ||
| "items": { | ||
| "type": "integer", | ||
| "minimum": 0, | ||
| "default": 0 | ||
| }, | ||
| "minItems": 3, | ||
| "maxItems": 3 | ||
| }, | ||
| "afterCount": { | ||
| "type": "array", | ||
| "description": "Number of neighboring data values after each dimension of the grid.", | ||
| "items": { | ||
| "type": "integer", | ||
| "minimum": 0, | ||
| "default": 0 | ||
| }, | ||
| "minItems": 3, | ||
| "maxItems": 3 | ||
| } | ||
| } | ||
| }, | ||
| "description": "The number of rows of neighboring tiles' voxel data." | ||
| } | ||
| }, | ||
| "required": ["dimensions"] | ||
| } |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The spec doesn't say much about the attributes used here. Some questions:
POSITION,NORMAL,TEXCOORD_n, etc.) have well-defined behavior in a voxel context? or are they treated the same as custom attributes like_TEMPERATUREhere?