Data Types, Style, Units

[revisionfx]

Is it a good idea to treat as integer what is not?
Perhaps you should have an additional column "Precision", e.g. 0.001, separate from Unit
e.g.: Anamorphic_Squeeze: Scale, 0.01, Number*
The unit like thing here is it's a scale factor, 1D scaler.
0.01 is the Precision hint is also usable for UI display (meta-data parametrization) and for fileOut (min decimal values).
I understand some old cameras don't have FPU and some legacy SMPTE document used such workarounds but it's 2023.

Maybe for each parameter block add a StorageType so if INT32 below vs FLT32 next example
e.g.: (conceptually)

"shutter_angle", needed, static, "Description", Scale, 0.01, 0, 360.0
camera_parameter_block {
"NumberStorageType": INT32 // static number values have two terms, second one is dividing factor

        (...)
        "shutter_angle": 18000, 100
       (...)

}

camera_parameter_block {

        "NumberStorageType":  FLT32

        (...)
        "shutter_angle": 180.00
       (...)

}

[palemieux]

@revisionfx See proposed serialization in camdkit at https://smpte.github.io/ris-osvp-metadata-camdkit/

[revisionfx]

It's what I am reading... and only questioning why put everything in a 32b int basis when it's not intrinsically the data type? . I am suggesting supporting type: "float" and defining range in variable natural range, not with X100 to fit in an int form. I never use JSON internally because of poor typing so I am not a good reference on that, but if you create a format, I am thinking maybe a good idea to support both and if int explicitly set a scaling factor in variable schema property so it's easier to parse for an app unambiguously.

e.g.: Focal Length even if in mm can have additional precision than integer mm (e.g. 27.53mm) particularly with zoom lenses. Why burn-in legacy imprecision (I understand this to be an issue with EXIF) ? On wide angle lenses 0.5 mm is a lot off. If not precise enough the camera tracker will try to solve additional precision. Won't be in int mm. It's not very nice also to build a C type API over that.

See below for example,

reinecke/otio-cookelensmetadata: A proof-of concept OpenTimelineIO adapter for the Cooke LMF lens metadata format. (github.com)

BTW: I asked Sen at Cooke to retrieve the bitbucket TonyD did back then using YAML for format examples/documentation. He said it will be available soon again.
Note, who interprets the data stream from the lens cable gets hexadecimal strings to turn into floating point values for most of the lens data parameters.

[palemieux]

nd only questioning why put everything in a 32b int basis when it's not intrinsically the data type?

Fixed point representation is used to since floats cannot achieve reliable interop across platforms/OS/languages.

I do not expect end users to tweak these files by hand. Do you?

We could recommend a way to present the information to the end user if you think it would help.

e.g.: Focal Length even if in mm can have additional precision than integer mm (e.g. 27.53mm) particularly with zoom lenses. Why burn-in legacy imprecision (I understand this to be an issue with EXIF) ?

Focal length is expressed in whole mm since it is the nominal focal length (i.e. the one printed on the side of the lens) and not the actual focal length. Do you know of any nominal focal lengths that use fractional mm?

The current fixed point representations can be modified to achieve higher precisions.

[revisionfx]

and only questioning why put everything in a 32b int basis when it's not intrinsically the data type?

Fixed point representation is used to since floats cannot achieve reliable interop across platforms/OS/languages.

I do not expect end users to tweak these files by hand. Do you?

It's not about user typing stuff directly, it's mapping this to other applications, API.

We could recommend a way to present the information to the end user if you think it would help.

If you consider storage in fixed point format most robust, I was suggesting adding an explicit per variable scaler (e.g.: 100X) and a precision hint for presentation (e.g. 0.01). I use the word hint as based on educated maximum expected precision in best case scenario also. I would also only use two units basis, mm for within camera-lens pairing (as sensor dimension and lens focal length starts in that space so is most user friendly) and meters for 3D scene inclusion (focal distance and camera position if a camera path is added as a block by someone). I would also define range in natural space (e.g. 0-360) as it's a description not the actual variable name-value.

e.g.: Focal Length even if in mm can have additional precision than integer mm (e.g. 27.53mm) particularly with zoom lenses. Why burn-in legacy imprecision (I understand this to be an issue with EXIF) ?

Focal length is expressed in whole mm since it is the nominal focal length (i.e. the one printed on the side of the lens) and not the actual focal length. Do you know of any nominal focal lengths that use fractional mm?

Any zoom lens no where the knob is set between two markings?

The current fixed point representations can be modified to achieve higher precisions.

[revisionfx]

Adding this as reference for thinking:

Already discussed over there that horizontal and vertical aperture (what is called physical dimensions here) should be in mm basis...

#usda 1.0
(
defaultPrim = "Camera01"
endTimeCode = 299
framesPerSecond = 30
metersPerUnit = 1
startTimeCode = 1
timeCodesPerSecond = 30
upAxis = "Y"
)
def Xform "SynthEyesGroup" (
kind = "assembly"
)
{
def Camera "Camera01"
{
float2 clippingRange = (1, 10000)
float focalLength = 0.1673091619
float focusDistance = 50
float fStop = 0
float horizontalAperture = 0.207264
float verticalAperture = 0.1165714286
float3 xformOp:rotateXYZ.timeSamples = {
1: (-23.7659, 79.9994, -14.3394),
2: (-23.7572, 79.9973, -14.3276),
3: (-23.7591, 79.9981, -14.3324),
4: (-23.7606, 79.9932, -14.336),
5: (-23.7759, 79.9901, -14.3476),
6: (-23.8225, 79.9843, -14.3906),
(...)

[revisionfx]

leaving values aside as you are defining your own format for interchange (not to generate a camera report)
Using a non-existing example to not go into discussion about a particular variable.

You could do something like below conceptually - as this would allow you to 1) remove some dependency on rational numbers and 2) have support for legacy formats or hardware that don't have FP unit and variation on that theme and 3) allow your dictionary to be "translated" to other languages where fixed_point arithmetic and rational numbers are not natural or natively supported and this so the data model can be carried over within other domains properly.

"horizontal_offset": { "type": "fixed_float_32", "normalizing_factor": 1000, "minimum": -65535.0, "maximum": 65535.0, "precision": 0.001, "unit":"pixels","animation": "dynamic", "value":[...]
}

values here are scaled by normalizing factor for write and on import divided by it would be usual use case.

or even better, split that in two or 3 (definition, description hints and value(s) that TBD when not static)
e.g. dynamic values having their own array, needing a start time sometimes to be matched to video start time...that can be explicitly defined in format for these streams.
and get value now in case of RT only has one value and would not need each sample to gather description data.
and for write to file, a majority of format have jump to data stream separate from variable definition and parametrization in file.
and description hints could even include short form tidbit description for direct absorption into a UI. "precision" here then becomes a hint if you already define normalization factor either for file write when translated to other language/format or UI number of values to display after the point.