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

Sun Apr 15 16:50:26 PDT 2018

I think there's potential for creating new formats in JSON schema which
reflect X3D types more closely, so that the schema and errors will be more
X3Dish.  However I am not sure how carried number formats are.

John

On Sun, Apr 15, 2018, 7:41 PM John Carlson <yottzumm at gmail.com> wrote:

> I think we should spend some time round tripping the X3DUOM back to XML
> schema, rather than Don going off and producing a JSON schema.   Plus we
> should work on generating XML schema versions from the X3DUOM and the
> version content in the standard.
>
> If someone could guide me, I can start work on taking JSON schema back to
> XML.   I will try to reach out to the JSON schema folks for help.
>
> We might find ways to enhance JSON schema this way.
>
> John
>
>
> On Sun, Apr 15, 2018, 4:47 PM Don Brutzman <brutzman at nps.edu> wrote:
>
>> [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
>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20180415/b8a43e6d/attachment-0001.html>