subframes and frame rate should be in Timecode object, not in a referenced TimecodeFormat object

[JGoldstone]

Quoting Hendrik:

In section "timing" -> "timecode" we specify hours, minutes, seconds, frames and "subframes" (in case the tracking system produces more than one sample per frame, as is always the case with interlaced video). The "subFrame" entry, however, is not on the same level as hours, minutes, seconds, frames but rather inside the "format" object which also contains the framerate. I believe it should be on the same level as hours, minutes, seconds, frames, and then the "format" object should contain constant information (or even remove "format" entirely and just specify the framerate on the same level as hours, minutes, seconds, frames, subframes because the "format" object never contains any further data).
So instead of:

"timing": {
  "timecode": {
    "hours": 1,
    "minutes": 2,
    "seconds": 3,
    "frames": 4,
    "format": {
      "frameRate": {
        "num": 24000,
        "denom": 1001
      },
      "subFrames": 1
    }
  }
}

it should be:

"timing": {
  "timecode": {
    "hours": 1,
    "minutes": 2,
    "seconds": 3,
    "frames": 4,
    "subFrames": 1,
    "format": {
      "frameRate": {
        "num": 24000,
        "denom": 1001
      }
    }
  }
}

or even:

"timing": {
  "timecode": {
    "hours": 1,
    "minutes": 2,
    "seconds": 3,
    "frames": 4,
    "subFrames": 1,
    "frameRate": {
      "num": 24000,
      "denom": 1001
    }
  }
}

Me (@JGoldstone ) personally, I favor the latter; once you have only a single parameter in a referenced object, unless there's some super clear semantic reason it's hard to see why you have a referenced object instead of just incorporating the parameter directly.

[jamesmosys]

Agreed - the latter is fine. Format is no longer meaningful.

[JGoldstone]

I am going with subFrame rather than subFrames as previously it was singluar, and only one sub-frame can be designated at a time.

[videofeedback]

I am joining the party to suggest a format that would accurately represent Sub-Frame divisions AND Sub-Frame count.
For example, Megapixel Helios represents Sub-Frames project based. You can either not choose to sub-divide sub-frames or you could divide in 1/2, 1/3, 1/4, 1/5, 1/6, 1/7, 1/8, 1/9, ~ 1/16.
Whereas "subFrames" is a Divisor of the Frame, and "subFrameCount" (to call it something right now) is the subframe number.
Example of the first Sub Frame Count from 1/16: "subFrames": 16, "subFrameCount": 2
I can check later how these two are named, but giving current workflows, both should be included.
My two cents.

[JGoldstone]

That would be a new numeric type, a constrained version of StrictlyPositiveRational, where the numerator could never exceed the denominator. I'm not opposed, but I do have a question ... actually, hold on, I probably have the relevant docs on hand ... yeah. The Helios doc clearly indicates that the sub-frame selector is 1-based, not 0-based:

[JGoldstone]

(Note that the red box and arrow were there before I pulled this image; what you really care about is the "Sub-Frame Timings" section that's at the top of the column just to the left of the rightmost column)

[videofeedback]

The Helios doc clearly indicates that the sub-frame selector is 1-based, not 0-based

Just to don't over-complicate the point, let's not get into this image because this is just a setting for gains expressed in floats from 0.0 to 2.0.
But now that we are on this image, yes, the Sub-Frame timings illustrates the Sub-Frame divisions in (ms, Shutter Angle or fractions = 1/60). This is a very useful illustration of how the Sub-Frames are divided.
The point is that when you don't enable Sub-Frames, the frame is just "1", and adding Sub-Frames it will sub-divide the frames according with the "Sub-Frames slices".
I still need to look at the JSON files (just a curiosity), on how that data is parsed.
But again, (regardless what name is going to be used), SubFrames and SubFramesCount (or something descriptive to represent these two values), will be very useful for most of these workflows.

[jamesmosys]

@videofeedback can you confirm this issue can be closed by #166 ?

[JGoldstone]

I'd suggest that for 1.0.0 we go with #166, where it's just a (hoisted) int, and we can later change the field to be either an int or a fraction compatibly (since all ints can be expressed as fractions with a unit denominator). @videofeedback , does that work and can we close this?

[jamesmosys]

@videofeedback I'm going to close this now ahead of the release - as @JGoldstone says we aren't blocked here. Please re-open if you think this needs more work later.