-
Notifications
You must be signed in to change notification settings - Fork 3.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Type information for metadata #12269
Comments
I did some experiments for this. The current state/draft is only in d7aeb52 (not in a shape for a PR, I guess). The type system, visibility concepts, and translation from JSDoc to TypeScript appear to simply be not powerful enough to reasonably support this. The typings that are drafted in the TypeScript snippet above can be translated into JDoc
So the resulting
and it does not appear to be possible to only export the These types (like Workarounds like indicating that in the name, like There's still the option of exporting only the actual type, without intermediate The expanded metadata type in terms of "raw values" (arrays) is this:
EDIT: Given that there are no tuples in JSDoc, this would boil down to
The expanded metadata type with "object types" (like
The latter looks OK-ish. But ....
It might be that we'll need both, unless we can ensure that the (In the worst case, there is a single function that could return both, depending on where the data is coming from - hopefully, this is not the case 🤞 ) |
Given that it is not possible to nicely construct the actual type in a clean bottom-up fashion, it will boil down to a fixed string in the This is drafted in #12315 (I'd lean towards closing this issue, but there might be a connection to #10455 : If the current |
tl;dr: There are some functions for accessing metadata in CesiumJS. These functions are generally declared to return
*
(akaany
) in the JSDoc. This is converted toany
for the TypeScript bindings. We could consider to narrow down the types that are returned by these functions.Context
CesiumJS supports the 3D Metadata Specification in two flavors: Once as part of the 3D Tiles 1.1 support, and once as part of the Cesium
EXT_structural_metadata
glTF extension. On the level of the API, these are treated equally (and intentionally so).There are examples like the MetadataGranularities sample where the metadata is accessed casually in the example sandcastle. But this is using a
private
API. The metadata is not exposed publicly right now. The representations of the metadata - in classes likeTilesetMetadata
,TileMetadata
... - follows (implicitly - not explicitly!) the interface that is defined asMetadataEntity
. This might become part of a public API at some point. The main function in this interface for accessing metadata is thegetProperty
function, which returns the value of a metadata property. Beyond that, the only function to obtain metadata values right now is viaCesium3DTileFeature.getProperty/Inherited
.The types of these functions are currently documented as
This is translated to
any
on the TypeScript layer.People might wish for more specific type information. This could be accomplished by adding "typedefs" on the JSDoc layer.
Possible approach
Translating the existing type system from the 3D Metadata Specification into TypeScript typings could be pretty straightforward. But there are caveats.
For example: In some cases, types like the
VEC3/FLOAT32
from the metadata specification are represented as anumber[]
array, and in other cases, they are represented as aCartesian3
. Both can make sense, depending on the context. But for the case of users accessing that metadata, the context is simply not known. Converting these types back and forth is usually easy, with thepack/unpack
functions. But this may be a bit inconvenient - and in order to know which function to call, the type has to be known, which is kind of a chicken-egg-problem.Another caveat is that in many cases, the types that are (and can be) represented as metadata already are limited. For example, in
EXT_structural_metadata
, a 'property texture' cannot containSTRING
valued metadata. Whether or not this is made explicit on the level of the type system at some point has to be decided.Draft of a possible approach
The following is a draft of a (largely) 1:1 translation of the 3D Metadata Specification type system into TypeScript. This is shown as a standalone file here, for quicker feedback and iterations:
(EDIT: Array types are not covered here - in many cases, this could be solved by appending a
[]
at the right place. Whether or not this is made explicit is also to be decided)Disclaimer:
One could make a case that this type information is of very limited use for clients. They can call a function (as drafted in the snippet above). And then they still don't know whether that value is a single
boolean
, or abigint[]
, or aMatrix4
. Actually using that type information will require it to be narrowed down - probably, by inspecting theClassProperty
of the metadata (if it is accessible...), or by some sort of runtime type checks.The text was updated successfully, but these errors were encountered: