Skip to content

MediaReference: spatial bounding box #771

Closed

Description

@rogernelson

Is the feature new development, or does it address existing functionality?

The existing OTIO structure already contains well-defined bounds for temporal metadata, but there is currently no way to express spatial bounds. When viewing a series of clips, particularly ones of different resolutions, it is useful to be able to define or determine the spatial bounds (ie viewport size) so that all the clips can be contained within it.

The MediaReference metadata of a clip currently contains a TimeRange that expresses the temporal bounds as the combination of a start_time and a duration property, and each of these are defined as Time structure that is a combination of rate and value properties. We would like to expand this concept to also express spatial bounds in a similar way.

Ideally, the spatial bounds would be expressed as a Box, which contains three properties: center, width and height. The width and height are similar to Time's value property in that they are unitless values as to be agnostic of any on particular coordinate system (pixels, cm, etc). The center is a Point structure that contains x and y properties that represent location of the center of the box in x and y coordinates.

The combination of the four related values width, height, x and y can then be used to derive the valid coordinate system for the spatial bounds. For example, a 16x9 box with a center at (0,0) would have x values in the range (-8, 8) and y values in the range (-4.5,4.5). These values can then be scaled to the actual image size being viewed while remaining independent of the units used to express the size of the image. Futhermore, since the center of the box is a user defined value, no assumptions about the location of the origin are required either. For example for a 16x9 Box in a coordinate system where the origin is in the bottom left, the center would be defined as (8,4.5) whereas in a coordinate system where the origin is the center the Box's center would be defined as (0,0).

Describe relevant implementation notes

The Box and Point primitives can be added to the existing opentime library, so they can live along side the Time and TimeRange ones and be de/serialized in a similar fashion. In addition, the Box should be supported as a template parameter to Optional so that older serialized json files are still valid even if they do not define bounds.

The MediaReference and its derivates can be modified to optionally take bounds argument defaulting to optional after their existing constructor arguments. This way both existing calls to the API and existing serialized json files still remain valid without requiring any client code to change.

The proposed json additions to the MediaReference schema looks like this:

"bounds": {
  "OTIO_SCHEMA": "Box.1"
  "center": {  
     "OTIO_SCHEMA": "Point.1"
     "x": 0.0,
     "y": 0.0
   }
   "width": 16.0,
   "height: 9.0
}

As with TimeRange, it is also useful to be able to determine the bounds of all the Clips in a container, so for this reason a bounds function can be added to the Composition and Timeline classes. When called it should calculate the union of all Boxes contained within any Clip MediaReferences yielding the minimum sized Box required to contain all the Composition's Clips.

Additional context

Slack discussion: https://academysoftwarefdn.slack.com/archives/CMQ9J4BQC/p1596741543292800

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions