[x3d-public] X3D JSON Schema Updates: determining event constraints for SFTime durations and timestamps

Sun Apr 15 13:45:18 PDT 2018

[summary:  SFTime durations are now better handled in tooltips/schema and object model, but further review is needed for absolute times with "negative" time values.]

On 4/14/2018 11:59 PM, John Carlson wrote:
> Don’s comments are in green, mine are varied colored.

[I have set my mailer's defaults for text, this is probably better for readability in mail archives.]

> Sorry for the early send.
> 
> John

[no worries, thanks for great review/feedback]

==========================

> *From: *Don Brutzman <mailto:brutzman at nps.edu>
> 
> 3. *Next Steps.*
> 
> Just prior to this task, I have separately added some minimum-allowed values to X3D XML Schema constraints on various SFTime duration fields.  They are all tested in X3DJSAIL satisfactorily. Hoping you can inspect them.  If agreed, please apply them to the JSON schema.
> 
> https://sourceforge.net/p/x3d/code/26640/#diff-4
> 
> Checking 3.3 standard:
> 
> X3DSoundSourceNode
> 
> duration_changed
> 
> Minimum Inclusive: -1
> 
> Not present in standard:
> 
> https://www.web3d.org/files/specifications/19775-1/V3.3/Part01/components/sound.html#X3DSoundSourceNode
> 
> Note:  This is the only -1 minimum in the schema for these patches, correct?

Correct, so far.  That -1 minimum value was included due to an X3D Abstract Specification note in AudioClip, which also appears in MovieTexture.

http://www.web3d.org/x3d/tooltips/X3dTooltips.html#AudioClip.duration_changed
http://www.web3d.org/x3d/tooltips/X3dTooltips.html#MovieTexture.duration_changed
"duration_changed is length of time in seconds for one cycle of media stream. Warning: duration value of -1 implies that media data has not yet loaded or is unavailable for some reason."

The tooltip is derived from nearly identical statements in X3D Abstract Spec, 16.4.1 AudioClip
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#AudioClip
and also 18.4.2 MovieTexture
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#MovieTexture

Note duration_changed is an SFTime duration interval, normally nonnegative, and not an absolute clock time. So using -1 as a sentinel value for missing media makes sense in this case.

> X3DTimeDependentNode
> 
> elapsedTime
> 
> Minimum Inclusive: 0

elapsedTime is a TimeSensor field measuring duration:

8.4.1 TimeSensor
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/time.html#TimeSensor

> timestamp
> 
> Minimum Inclusive: 0

this field is from DIS component, for several nodes, which comes from received DIS PDU packet.  So -1 is not a valid outputOnly event value.

> cycleInterval
> 
> Minimum Inclusive: 0
> 
> readInterval
> 
> Minimum Inclusive: 0
> 
> writeInterval
> 
> Minimum Inclusive: 0

The rest of these are durations, not absolute times.  Thus nonnegative.

> Not present in standard:
> 
> https://www.web3d.org/files/specifications/19775-1/V3.3/Part01/components/time.html#X3DTimeDependentNode
>> TimeSensor
> 
> cycleTime
> 
> Minimum Inclusive: 0
> 
> time
> 
> Minimum Inclusive: 0
> 
> Minimums not included in standard:
> 
> https://www.web3d.org/files/specifications/19775-1/V3.3/Part01/components/time.html#TimeSensor

Yes, I think those allowed-range minimums are omissions that need to be added to specification (especially since -1 is not a meaningful duration value).

> X3DNetworkSensorNode
> 
> readInterval
> 
> Minimum Inclusive: 0
> 
> writeInterval
> 
> Minimum Inclusive: 0
> 
> timestamp
> 
> Minimum Inclusive: 0

Actually those range limits [0, infinity) are found in multiple respective node signatures where they appear, in DIS component:

28 Distributed interactive simulation (DIS) component
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/dis.html

*Another specification comment*: we might consider allowing 0 for readInterval and writeInterval values, perhaps allowing it as a browser-handled special case corresponding to IEEE DIS Specification read/write rules..

> disableTime
> 
> Minimum Inclusive: 0
> 
> None of these are present in
> 
> https://www.web3d.org/files/specifications/19775-1/V3.3/Part01/components/networking.html#X3DNetworkSensorNode
Field disableTime appears in both RigidBody and RigidBodyCollection, and is another duration value:

37.4.10 RigidBody
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rigid_physics.html#RigidBody
37.4.11 RigidBodyCollection
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rigid_physics.html#RigidBodyCollection

"The disable fields define conditions for when the body ceases to considered as part of the rigid body calculations and should be considered as at rest."

So all of the preceding output fields are time durations, and the limits are justifiable.  Specification comment to follow - but there is a bit more to think through first.

==========================

4. Next, moving past durations (which are not negative since time only progresses) to absolute time values.  Note that by definition, SFTime-typed fields can have either be -1, 0 or positive double-precision values.

5.3.15 SFTime and MFTime
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/fieldsDef.html#SFTimeAndMFTime
"Time values are specified as the number of seconds from a specific time origin. Typically, SFTime fields represent the number of seconds since Jan 1, 1970, 00:00:00 GMT. The default value of an uninitialized SFTime field is -1."

I think we need to honor that range restriction in the XML and JSON schema (indeed the X3D Unified Object Model).  However this would be a good discussion topic first.

Was wondering if there ever cases where negative values for SFTime other than -1 are useful... didn't think so, based on the preceding clause 5.3.15.  Then found this:

8.2.2 Time origin
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/time.html#Timemodel
"Time (0.0) is equivalent to 00:00:00 GMT January 1, 1970. Absolute times are specified in SFTime or MFTime fields as double-precision floating point numbers representing seconds. Negative absolute times are interpreted as happening before 1970."

So there may be a semantic mismatch here... do we indeed allow negative SFTime values? Can reserved -1 sentinel values indicate special semantics without interfering with negative time values?  Hmmm...

One can easily imagine a historical use case where we want to synchronize animations of historic events... so if we didn't allow negative values, then we would likely need a TimeOrigin or other mechanism...

So we really need to get clear on SFTime representations.

> I don’t know enough about the standard to show whether these are proper additions or not.

Am mainly hoping that you can apply these duration constraints consistently within the JSON schema, so that we keep them synchronized.

> You say separately, but I thought this was a group thing.  Can you show me the Mantis issues where we are adding these, so I have a better idea of what I am concurring to?

Hope this helps.  Spec issues will follow, using Spec Feedback Form and Mantis - just didn't want to muddle things prematurely while posing/testing duration changes.

This email thread gets the ball rolling (or perhaps the clock ticking!)... we will need an X3D Working Group call to tackle this topic and look at SFTime issues/actions.

==========================

5. Next, regarding X3D JSON Schema.

> Normally, I copy the 3.3 JSON schema to 3.0, 3.1, 3.2 and 4.0, so that will be what I do.  If this is drastically different than previous schemas for those versions, let me know.  I don’t know what I’ll do, but at least I’ll know.

You can see all the variations corresponding to X3D versions in the specification itself:

X3D Abstract Specification,  Annex Z (normative) Version content
http://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/versionContent.html

So yes there are a lot of differences.  Each time we get modifications to X3D XML DTD or Schema it usually takes me maybe two hours to carefully apply diffs from X3D v3.3 to versions 3.0, 3.1, 3.2 and 4.0 then update documentation.

> I think it’s best to autogenerate these schema fields as snippets from the X3DUOM and upgrade the JSON schema by using autogenerated snippets.    It appears according to the standard that many of these fields are new ones. Plus snippets are less error prone.   So let’s get them into the object model soon.

Agreed, that is getting onto my long-range radar... autogenerating JSON Schema via XSLT stylesheet will be an excellent test of X3D Unified Object Model, and prose/links i that page are now updated online as well.

X3D Unified Object Model (X3DUOM)
http://www.web3d.org/specifications/X3DUOM.html

Extra-credit issues:
a. generating X3DObjectModel-3.3.xml files for each X3D version
    http://www.web3d.org/specifications/X3DObjectModel-3.3.xml

b. both X3DJSAIL and X3DJSONLD may have enough information embedded already to generate matching JSON schemas.

> On 4/11/2018 7:38 AM, John Carlson wrote:
> 
>  > to this mantis:
> 
>  > http://www.web3d.org/member-only/mantis/view.php?id=1227
> 
> I have updated that specification-draft editor issue and assigned it to me.  Will test further before updating draft X3D JSON specification in github.
> 
> (As noted earlier, it is better to submit spec changes via the spec comment form, since some muttered incantations are involved).
> 
> Wondering, should we immediately try for draft-07?  Or do you think that the differences are minuscule because they've only just started that version?
> 
> I think we only have to change the referenced metaschema for draft-07.  The draft-07 schema is at the normal link (which would require a one character change), but I don’t know if that’s the official URL.  I believe references to schemas will vary drastically with draft-08 if it ever comes out, or they may continue to offer a compatible single point of reference.   I think we should go with the one character change, and upgrade to draft-08 once we have the autogenerated schema.
> 
> John

again thanks for all scrutiny, these are important to get right.  interlocking toolsets are certainly helping us "dial in" everything with precision.

all the best, Don
-- 
Don Brutzman  Naval Postgraduate School, Code USW/Br       brutzman at nps.edu
Watkins 270,  MOVES Institute, Monterey CA 93943-5000 USA   +1.831.656.2149
X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman