PictureDescriptor (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.model

## Interface PictureDescriptor

- All Superinterfaces:
    AAFFileDescriptor, EssenceDescriptor, InterchangeObject, MediaEntity, MetadataObject
  All Known Subinterfaces:
    CDCIDescriptor, CDCIDescriptor, MPEGVideoDescriptor, PictureDescriptor, RGBADescriptor
  All Known Implementing Classes:
    CDCIDescriptorImpl, MPEGVideoDescriptorImpl, PictureDescriptorImpl, RGBADescriptorImpl

      public interface PictureDescriptor
      extends AAFFileDescriptor

  Specifies the description of video content data formatted either using RGBA or luminance/chrominance formatting.

  The geometry properties accessed by `set`/`getStoredView()`, `set`/`getSampledView()` and `set`/`getDisplayView()` describe the dimensions and meaning of the stored pixels in the image. The geometry describes the pixels of an uncompressed image. Consequently, the geometry properties are independent of the compression and subsampling of that data.

  Three separate geometries - stored, sampled, and display views - are used to define a set of different views on uncompressed digital data. All views are constrained to rectangular regions, which means that storage and sampling has to be rectangular.

  The relationships among the views can be shown by the following rectangles, representing areas of a video image:

            +------------------+
            |                  |
            |   Stored View    |
            |                  |           +--------------+
            +------------------+ <-------- |              |
            |                  |  Sample   | Analog Video |
            |   Sampled View   |  Process  |    Source    |
            |                  |           | Information  |
            | +--------------+ |           |              |
            | |              | |           |              |
            | | Display View | |           |              |
            | |              | |           |              |
            | +--------------+ |           |              |
            |                  |           |              |
            +------------------+ <-------- |              |
                                           +--------------+

  The stored view is the entire data region corresponding to a single uncompressed frame or field of the image, and is defined by its horizontal and vertical dimension properties. The stored view may include data that is not derived from, and would not usually be translated back to, analog data.

  The sampled view is defined to be the rectangular dimensions in pixels corresponding to the digital data derived from an analog or digital source. These pixels reside within the rectangle defined by the stored view. This would include the image and auxiliary information included in the analog or digital source. For the capture of video signals, the mapping of these views to the original signal is determined by the video line map property.

  The display view is the rectangular size in pixels corresponding to the viewable area. These pixels contain image data suitable for scaling, display, warping, and other image processing. The display view offsets are relative to the stored view, not to the sampled view.

  Although typically the display view is a subset of the sampled view, it is possible that the viewable area may not be a subset of the sampled data. It may overlap or even encapsulate the sampled data. For example, a subset of the input image might be centered in a computer-generated blue screen for use in a chroma key effect. In this case the viewable pixels on disk would contain more than the sampled image.

  Each of these data views will have a width and height value. Both the sampled view and the display view also have offsets relative to the top left corner of the stored view.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static AlphaTransparencyType` | `ALPHATRANSPARENCY_DEFAULT` Default value for the optional alpha transparency property, which is `AlphaTransparencyType.MinValueTransparent`.
    `static int` | `DISPLAYF2OFFSET_DEFAULT` Default value for the optional display f2 offset property, which is 0.
    `static int` | `IMAGEALIGNMENTFACTOR_DEFAULT` Default value for the image alignment factor property, which is 1.
    `static int` | `IMAGEENDOFFSET_DEFAULT` Default value for the image end offset property, which is 0.
    `static int` | `IMAGESTARTOFFSET_DEFAULT` Default value for the image start offset property, which is 0.
    `static int` | `STOREDF2OFFSET_DEFAULT` Default value for the optional stored f2 offset property, which is 0.
    `static AUID` | `Uncompressed` Value representing no compression, which is that the compression property is omitted (`null`).

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `areDisplayValuesPresent()` Returns whether this picture descriptor contains a display view.
    `boolean` | `areSampledValuesPresent()` Returns whether this picture descriptor contains a sample area values dimensions and offsets.
    `PictureDescriptor` | `clone()` Create a cloned copy of this picture descriptor.
    `byte` | `getActiveFormatDescriptor()` Returns the active format descriptor property for the picture descriptor, which specifies the desired framing of the content within the displayed image (4:3 in 16:9 etc.).
    `AlphaTransparencyType` | `getAlphaTransparency()` Returns the alpha transparency property of this picture descriptor, which specifies whether the minimum alpha value or the maximum alpha value indicates transparency.
    `AUID` | `getCodingEquations()` Returns the coding equations property of this picture descriptor, which specifies the coding equations to convert RGB image components to component color difference image components.
    `AUID` | `getColorPrimaries()` Returns the color primaries property for the picture descriptor.
    `int` | `getDisplayF2Offset()` Returns the display field 2 offset property of this picture descriptor.
    `int` | `getDisplayHeight()` Returns the height component of the display view of the picture descriptor.
    `int[]` | `getDisplayView()` Returns the dimensions of the display view of this picture descriptor.
    `int` | `getDisplayWidth()` Returns the width component of the display view of the picture descriptor.
    `int` | `getDisplayXOffset()` Returns the X offset of the display view of the picture descriptor.
    `int` | `getDisplayYOffset()` Returns the Y offset of the display view of the picture descriptor.
    `FieldNumber` | `getFieldDominance()` Returns the field dominance property of this picture descriptor, which specifies whether field 1 or field 2 is dominant in images composed of two interlaced fields.
    `LayoutType` | `getFrameLayout()` Returns the frame layout for this picture descriptor, which describes whether all data for a complete sample is in one frame or is split into more than one field.
    `int` | `getImageAlignmentFactor()` Sets the image alignment factor property of this picture descriptor, which specifies the alignment when storing the digital essence.
    `Rational` | `getImageAspectRatio()` Gets the image aspect ratio property of this picture descriptor, which describes the ratio between the horizontal size and the vertical size in the intended final image.
    `int` | `getImageEndOffset()` Returns the field end offset property of this picture descriptor, which specifies the number of unused bytes at the end of each video field.
    `int` | `getImageStartOffset()` Returns the image start offset property of this picture descriptor, which specifies the number of unused bytes at the start of each video field.
    `AUID` | `getPictureCompression()` Returns the kind of compression and format of compression information of the video essence data described by this picture descriptor.
    `int` | `getSampledHeight()` Returns the height component of the sampled view of this picture descriptor.
    `int[]` | `getSampledView()` Returns the dimensions of the sampled view of this picture descriptor.
    `int` | `getSampledWidth()` Returns the width component of the sampled view of this picture descriptor.
    `int` | `getSampledXOffset()` Returns the X offset component to the sampled view of this picture descriptor.
    `int` | `getSampledYOffset()` Returns the Y offset component to the sampled view of this picture descriptor.
    `SignalStandardType` | `getSignalStandard()` Returns the signal standard property of this picture descriptor.
    `int` | `getStoredF2Offset()` Returns the stored field 2 offset property of this picture descriptor, which specifies a topness adjustment for the stored picture.
    `int` | `getStoredHeight()` Returns the height component of the dimension of the complete stored view.
    `int[]` | `getStoredView()` Returns the dimension of the stored view of this picture descriptor.
    `int` | `getStoredWidth()` Returns the width component of the dimension of the complete stored view.
    `AUID` | `getTransferCharacteristic()` Returns the opto-electronic transfer characteristic of this digital image descriptor.
    `int[]` | `getVideoLineMap()` Returns the video line map property of this picture descriptor, which specifies the scan line in the analog source that corresponds to the beginning of each digitized field.
    `int` | `getVideoLineMapSize()` Returns the number of elements in the video line map property array of this picture descriptor.
    `void` | `setActiveFormatDescriptor(Byte activeFormatDescriptor)` Sets the active format descriptor property for the picture descriptor, which specifies the desired framing of the content within the displayed image (4:3 in 16:9 etc.).
    `void` | `setAlphaTransparency(AlphaTransparencyType alphaTransparency)` Sets the alpha transparency property of this picture descriptor, which specifies whether the minimum alpha value or the maximum alpha value indicates transparency.
    `void` | `setCodingEquations(AUID codingEquations)` Sets the coding equations property of this picture descriptor, which specifies the coding equations to convert RGB image components to component color difference image components.
    `void` | `setColorPrimaries(AUID colorPrimaries)` Sets the color primaries property for this picture descriptor.
    `void` | `setDisplayF2Offset(Integer displayF2Offset)` Sets the display field 2 offset property of this picture descriptor.
    `void` | `setDisplayView(int displayHeight, int displayWidth, int displayXOffset, int displayYOffset)` Sets the dimension of display view of this picture descriptor.
    `void` | `setFieldDominance(FieldNumber fieldDominance)` Sets the field dominance property of this picture descriptor, which specifies whether field 1 or field 2 is dominant in images composed of two interlaced fields.
    `void` | `setFrameLayout(LayoutType frameLayout)` Sets the frame layout for this picture descriptor, which describes whether all data for a complete sample is in one frame or is split into more than one field.
    `void` | `setImageAlignmentFactor(Integer imageAlignmentFactor)` Sets the image alignment factor property of this picture descriptor which specifies the alignment when storing the digital essence.
    `void` | `setImageAspectRatio(Rational imageAspectRatio)` Sets the image aspect ratio property of this picture descriptor, which describes the ratio between the horizontal size and the vertical size in the intended final image.
    `void` | `setImageEndOffset(Integer imageEndOffset)` Sets the image end offset property of this picture descriptor, which specifies the number of unused bytes at the end of each video field.
    `void` | `setImageStartOffset(Integer imageStartOffset)` Sets the image start offset property of this picture descriptor, which specifies the number of unused bytes at the start of each video field.
    `void` | `setPictureCompression(AUID pictureCompression)` Sets the kind of compression and format of the compression information of the video essence data described by this picture descriptor.
    `void` | `setSampledView(int sampledHeight, int sampledWidth, int sampledXOffset, int sampledYOffset)` Sets the dimensions of the sampled view of this picture descriptor.
    `void` | `setSignalStandard(SignalStandardType signalStandard)` Sets the signal standard property of this picture descriptor, which specifies the underlying signal standard used to define the raster.
    `void` | `setStoredF2Offset(Integer storedF2Offset)` Sets the stored field 2 offset property of this picture descriptor, which specifies a topness adjustment for the stored picture.
    `void` | `setStoredView(int storedHeight, int storedWidth)` Sets the dimension of the stored view of this picture descriptor.
    `void` | `setTransferCharacteristic(AUID transferCharacteristic)` Sets the opto-electronic transfer characteristic of this digital image descriptor.
    `void` | `setVideoLineMap(int[] videoLineMap)` Sets the video line map property of this picture descriptor, which specifies the scan line in the analog source that corresponds to the beginning of each digitized field.

    - ### Methods inherited from interface tv.amwa.maj.model.AAFFileDescriptor

      `getCodec, getContainerFormat, getEssenceLength, getLinkedTrackID, getSampleRate, setCodec, setContainerFormat, setEssenceLength, setLinkedTrackID, setSampleRate`

    - ### Methods inherited from interface tv.amwa.maj.model.EssenceDescriptor

      `appendLocator, appendSubDescriptor, clearLocators, countLocators, countSubDescriptors, getLocatorAt, getLocators, getSubDescriptorAt, getSubDescriptors, insertLocatorAt, insertSubDescriptorAt, prependLocator, prependSubDescriptor, removeLocatorAt, removeSubDescriptorAt`

    - ### Methods inherited from interface tv.amwa.maj.model.InterchangeObject

      `addApplicationPlugin, clearApplicationPlugins, containsApplicationPlugin, containsApplicationPlugin, countApplicationPlugins, deepEquals, disableGenerationTracking, enableGenerationTracking, equals, getApplicationPlugins, getGeneration, getLinkedGenerationID, getObjectClass, isGenerationTracked, removeApplicationPlugin, removeApplicationPlugin, setLinkedGenerationID, setObjectClass, toString`

    - ### Methods inherited from interface tv.amwa.maj.industry.MediaEntity

      `getPersistentID, setPersistentIndex`

- - ### Field Detail

    - #### Uncompressed

          static final AUID Uncompressed

      Value representing no compression, which is that the compression property is omitted (`null`).

      See Also:
        `getPictureCompression()`, `setPictureCompression(AUID)`

    - #### STOREDF2OFFSET_DEFAULT

          static final int STOREDF2OFFSET_DEFAULT

      Default value for the optional stored f2 offset property, which is 0.

      See Also:
        `getStoredF2Offset()`, `setStoredF2Offset(Integer)`, Constant Field Values

    - #### DISPLAYF2OFFSET_DEFAULT

          static final int DISPLAYF2OFFSET_DEFAULT

      Default value for the optional display f2 offset property, which is 0.

      See Also:
        `getDisplayF2Offset()`, `setDisplayF2Offset(Integer)`, Constant Field Values

    - #### ALPHATRANSPARENCY_DEFAULT

          static final AlphaTransparencyType ALPHATRANSPARENCY_DEFAULT

      Default value for the optional alpha transparency property, which is `AlphaTransparencyType.MinValueTransparent`.

      See Also:
        `getAlphaTransparency()`, `setAlphaTransparency(AlphaTransparencyType)`

    - #### IMAGEALIGNMENTFACTOR_DEFAULT

          static final int IMAGEALIGNMENTFACTOR_DEFAULT

      Default value for the image alignment factor property, which is 1.

      See Also:
        `getImageAlignmentFactor()`, `setImageAlignmentFactor(Integer)`, Constant Field Values

    - #### IMAGESTARTOFFSET_DEFAULT

          static final int IMAGESTARTOFFSET_DEFAULT

      Default value for the image start offset property, which is 0.

      See Also:
        `getImageStartOffset()`, `setImageStartOffset(Integer)`, Constant Field Values

    - #### IMAGEENDOFFSET_DEFAULT

          static final int IMAGEENDOFFSET_DEFAULT

      Default value for the image end offset property, which is 0.

      See Also:
        `getImageEndOffset()`, `setImageEndOffset(Integer)`, Constant Field Values

  - ### Method Detail

    - #### setPictureCompression

          void setPictureCompression(AUID pictureCompression)

      Sets the kind of compression and format of the compression information of the video essence data described by this picture descriptor. If there is no compression, set this optional property to `Uncompressed` or `null`.

      Parameters:
        `pictureCompression` - Kind of compression and format of the compression information of the video essence data, or `Uncompressed` if the image is uncompressed.
      See Also:
        `Uncompressed`

    - #### getPictureCompression

          AUID getPictureCompression()
                              throws PropertyNotPresentException

      Returns the kind of compression and format of compression information of the video essence data described by this picture descriptor. If the image data is uncompressed, a `PropertyNotPresentException` will be thrown.

      Returns:
        Kind of compression and format of compression information of the video essence data.
      Throws:
        `PropertyNotPresentException` - The optional compression property is not present in this picture descriptor, indicating that the described image essence data is uncompressed.

    - #### setStoredView

          void setStoredView(@UInt32
                             int storedHeight,
                             @UInt32
                             int storedWidth)
                      throws IllegalArgumentException

      Sets the dimension of the stored view of this picture descriptor. Typically, this includes leading blank video lines, any VITC lines, as well as the active picture area.

      Parameters:
        `storedHeight` - Number of pixels in vertical dimension of stored view.
        `storedWidth` - Number of pixels in horizontal dimension of stored view.
      Throws:
        `IllegalArgumentException` - One or both of the given stored width and height properties is/are negative, which is not permitted.

    - #### getStoredView

          int[] getStoredView()

      Returns the dimension of the stored view of this picture descriptor. Typically, this includes leading blank video lines, any VITC lines, as well as the active picture area.

      The value returned is an array of two integer values. The first element of the array (index 0) contains the stored height and the second element of the array (index 1) contains the stored width.

      Returns:
        Dimension of the stored view.
      See Also:
        `getStoredHeight()`, `getStoredWidth()`

    - #### getStoredHeight

          int getStoredHeight()

      Returns the height component of the dimension of the complete stored view. Typically, this includes leading blank video lines, any VITC lines, as well as the active picture area.

      Returns:
        Height component of the complete stored view.
      See Also:
        `getStoredView()`

    - #### getStoredWidth

          int getStoredWidth()

      Returns the width component of the dimension of the complete stored view.

      Returns:
        Width component of the complete stored view.
      See Also:
        `getStoredView()`

    - #### setSampledView

          void setSampledView(@UInt32
                              int sampledHeight,
                              @UInt32
                              int sampledWidth,
                              @Int32
                              int sampledXOffset,
                              @Int32
                              int sampledYOffset)
                       throws IllegalPropertyValueException

      Sets the dimensions of the sampled view of this picture descriptor. Typically, this includes any VITC lines as well as the active picture area, but excludes leading blank video lines. The offset is specified relative to the rectangle specified by the stored view.

      All properties are optional and are set as follows:

      - `sampledHeight` - The default value is the stored height, so use `getStoredView()[0]` to set the default value.
      - `sampledWidth` - The default value is the stored width, so use `getStoredView()[1]` to set the default value.
      - `displayXOffset` - The default value is 0, so use 0 to select the default.
      - `displayYOffset` - The default value is 0, so use 0 to select the default.

      The sampled view values are either all present or all omitted. Calling this method will mean sampled view values are present. To find out whether the sampled view properties are present, call `areSampledValuesPresent()`.

      Parameters:
        `sampledHeight` - Number of pixels in vertical dimension of sampled view.
        `sampledWidth` - Number of pixels in horizontal dimension of sampled view.
        `sampledXOffset` - Number of pixels from top left corner of the stored view.
        `sampledYOffset` - Number of pixels from top left corner of the stored view.
      Throws:
        `IllegalPropertyValueException` - The area specified by the sampled width and sampled X offset is outside the stored view, or the area specified by the sampled height and sampled Y offset is outside the stored view.

    - #### getSampledView

          int[] getSampledView()

      Returns the dimensions of the sampled view of this picture descriptor. Typically, this includes any VITC lines as well as the active picture area, but excludes leading blank video lines. The offset is specified relative to the rectangle specified by the stored view.

      The value returned is an array of four integer values. The index of the values correspond to:

      - `0` - sampled height - Number of pixels in vertical dimension of sampled view.
      - `1` - sampled width - Number of pixels in horizontal dimension of sampled view.
      - `2` - sampled X offset - Number of pixels from top left corner of stored view.
      - `3` - sampled Y offset - Number of pixels from top left corner of stored view.

      The sampled view properties are either all present or all omitted. If the properties are omitted, the default value is returned which is an area equivalent to the stored view. To find out whether the sampled view properties are present, call `areSampledValuesPresent()`.

      Returns:
        Dimensions of the sampled view.
      See Also:
        `getSampledHeight()`, `getSampledWidth()`, `getSampledXOffset()`, `getSampledYOffset()`

    - #### getSampledHeight

          int getSampledHeight()

      Returns the height component of the sampled view of this picture descriptor. Typically, this includes any VITC lines as well as the active picture area, but excludes leading blank video lines.

      Returns:
        Height component of the sampled view.
      See Also:
        `getSampledView()`

    - #### getSampledWidth

          int getSampledWidth()

      Returns the width component of the sampled view of this picture descriptor.

      Returns:
        Width component of the sampled view.
      See Also:
        `getSampledView()`

    - #### getSampledXOffset

          int getSampledXOffset()

      Returns the X offset component to the sampled view of this picture descriptor. The offset is specified relative to the rectangle specified by the stored view.

      Returns:
        X offset component to the sampled view.
      See Also:
        `getSampledView()`, `getStoredView()`

    - #### getSampledYOffset

          int getSampledYOffset()

      Returns the Y offset component to the sampled view of this picture descriptor. The offset is specified relative to the rectangle specified by the stored view.

      Returns:
        Y offset component to the sampled view.
      See Also:
        `getSampledView()`, `getStoredView()`

    - #### setDisplayView

          void setDisplayView(@UInt32
                              int displayHeight,
                              @UInt32
                              int displayWidth,
                              @Int32
                              int displayXOffset,
                              @Int32
                              int displayYOffset)
                       throws IllegalPropertyValueException

      Sets the dimension of display view of this picture descriptor. Typically, this includes the active picture area, but excludes leading blank video lines and any VITC lines. The offset is specified relative to the rectangle specified by the stored view.

      All properties are optional and are set as follows:

      - `displayHeight` - The default value is the stored height, so use `getStoredView()[0]` to set the default value.
      - `displayWidth` - The default value is the stored width, so use `getStoredView()[1]` to set the default value.
      - `displayXOffset` - The default value is 0, so use 0 to select the default.
      - `displayYOffset` - The default value is 0, so use 0 to select the default.

      The display view values are either all present or all omitted. Calling this method successfully will mean display view values are present. To find out whether the display view properties are present, call `areDisplayValuesPresent()`.

      Parameters:
        `displayHeight` - Number of pixels in vertical dimension of display view.
        `displayWidth` - Number of pixels in vertical dimension of display view.
        `displayXOffset` - Number of pixels from the top-left corner of the stored view.
        `displayYOffset` - Number pixels from the top-left corner of the stored view.
      Throws:
        `IllegalPropertyValueException` - The area specified by display width and display X offset properties is outside the stored view, or the area specified by display height and display Y offset properties is outside the stored view.

    - #### getDisplayView

          int[] getDisplayView()

      Returns the dimensions of the display view of this picture descriptor. Typically, this includes the active picture area, but excludes leading blank video lines and any VITC lines. The offset is specified relative to the rectangle specified by the stored view.

      The value returned is an array of four integer values. The index of the values correspond to:

      - `0` - display height - Number of pixels in vertical dimension of display view.
      - `1` - display width - Number of pixels in horizontal dimension of display view.
      - `2` - display X offset - Number of pixels from top left corner of stored view.
      - `3` - display Y offset - Number of pixels from top left corner of stored view.

      The display view properties are either all present or all omitted. If the properties are omitted, the default value is returned which is an area equivalent to the stored view. To find out whether the display view properties are present, call `areDisplayValuesPresent()`.

      Returns:
        Dimensions of the display view.
      See Also:
        `getDisplayHeight()`, `getDisplayWidth()`, `getDisplayXOffset()`, `getDisplayYOffset()`

    - #### getDisplayHeight

          int getDisplayHeight()

      Returns the height component of the display view of the picture descriptor. Typically, this includes the active picture area, but excludes leading blank video lines and any VITC lines.

      Returns:
        Height component of the display view.
      See Also:
        `getDisplayView()`

    - #### getDisplayWidth

          int getDisplayWidth()

      Returns the width component of the display view of the picture descriptor.

      Returns:
        Width component of the display view.
      See Also:
        `getDisplayView()`

    - #### getDisplayXOffset

          int getDisplayXOffset()

      Returns the X offset of the display view of the picture descriptor. The offset is specified relative to the rectangle specified by the stored view.

      Returns:
        X offset of the display view.
      See Also:
        `getDisplayView()`, `getStoredView()`

    - #### getDisplayYOffset

          int getDisplayYOffset()

      Returns the Y offset of the display view of the picture descriptor. The offset is specified relative to the rectangle specified by the stored view.

      Returns:
        Y offset of the display view.
      See Also:
        `getDisplayView()`, `getStoredView()`

    - #### setFrameLayout

          void setFrameLayout(LayoutType frameLayout)
                       throws NullPointerException

      Sets the frame layout for this picture descriptor, which describes whether all data for a complete sample is in one frame or is split into more than one field.

      Parameters:
        `frameLayout` - Frame layout for the picture descriptor.
      Throws:
        `NullPointerException` - The given frame layout is `null`.

    - #### getFrameLayout

          LayoutType getFrameLayout()

      Returns the frame layout for this picture descriptor, which describes whether all data for a complete sample is in one frame or is split into more than one field.

      Returns:
        Frame layout for the picture descriptor.

    - #### setVideoLineMap

          void setVideoLineMap(@VideoLineMap
                               int[] videoLineMap)
                        throws NullPointerException

      Sets the video line map property of this picture descriptor, which specifies the scan line in the analog source that corresponds to the beginning of each digitized field. For single-field video, there is 1 value in the array. For interleaved video, there are 2 values in the array.

      Parameters:
        `videoLineMap` - Video line map for the picture descriptor.
      Throws:
        `NullPointerException` - The given video line map is `null`.
        `IllegalArgumentException` - The size of the video line map must be 1 or 2 for this picture descriptor.

    - #### getVideoLineMap

          @VideoLineMap
          int[] getVideoLineMap()

      Returns the video line map property of this picture descriptor, which specifies the scan line in the analog source that corresponds to the beginning of each digitized field. For single-field video, there is 1 value in the array. For interleaved video, there are 2 values in the array.

      Returns:
        Video line map property of this picture descriptor.

    - #### getVideoLineMapSize

          @UInt32
          int getVideoLineMapSize()

      Returns the number of elements in the video line map property array of this picture descriptor.

      Returns:
        Number of elements in the video line map property array.
      See Also:
        `getVideoLineMap()`

    - #### setImageAspectRatio

          void setImageAspectRatio(Rational imageAspectRatio)
                            throws NullPointerException

      Sets the image aspect ratio property of this picture descriptor, which describes the ratio between the horizontal size and the vertical size in the intended final image.

      Parameters:
        `imageAspectRatio` - Ratio between horizontal and vertical size of the intended final image.
      Throws:
        `NullPointerException` - The given image aspect ratio is `null`.

    - #### getImageAspectRatio

          Rational getImageAspectRatio()

      Gets the image aspect ratio property of this picture descriptor, which describes the ratio between the horizontal size and the vertical size in the intended final image.

      Returns:
        Ratio between horizontal and vertical size of the intended final image.

    - #### setAlphaTransparency

          void setAlphaTransparency(AlphaTransparencyType alphaTransparency)
                             throws NullPointerException

      Sets the alpha transparency property of this picture descriptor, which specifies whether the minimum alpha value or the maximum alpha value indicates transparency. To omit this optional property, call this method with `null`.

      Parameters:
        `alphaTransparency` - Alpha transparency orientation for this picture descriptor.
      Throws:
        `NullPointerException`
      See Also:
        `ALPHATRANSPARENCY_DEFAULT`

    - #### getAlphaTransparency

          AlphaTransparencyType getAlphaTransparency()

      Returns the alpha transparency property of this picture descriptor, which specifies whether the minimum alpha value or the maximum alpha value indicates transparency. This is an optional property and if the value is omitted, the default value of AlphaTransparencyType.MinValueTransparent is returned.

      Returns:
        Alpha transparency orientation for this picture descriptor.
      See Also:
        `ALPHATRANSPARENCY_DEFAULT`

    - #### setImageAlignmentFactor

          void setImageAlignmentFactor(@UInt32
                                       Integer imageAlignmentFactor)
                                throws IllegalArgumentException

      Sets the image alignment factor property of this picture descriptor which specifies the alignment when storing the digital essence.

      For example, a value of 16 means that the image is stored on 16-byte boundaries. The starting point for a field will always be a multiple of 16 bytes. If the field does not end on a 16-byte boundary, it is padded out to the next 16-byte boundary.

      Set this optional property to `null` to omit the property. The default value of this property is 1.

      Parameters:
        `imageAlignmentFactor` - Image alignment factor of this picture descriptor.
      Throws:
        `IllegalArgumentException` - Cannot set the image alignment factor to a negative value for this picture descriptor.

    - #### getImageAlignmentFactor

          @UInt32
          int getImageAlignmentFactor()

      Sets the image alignment factor property of this picture descriptor, which specifies the alignment when storing the digital essence.

      For example, a value of 16 means that the image is stored on 16-byte boundaries. The starting point for a field will always be a multiple of 16 bytes. If the field does not end on a 16-byte boundary, it is padded out to the next 16-byte boundary.

      This property is optional and the default value of 1 will be returned if it is currently omitted.

      Returns:
        Image alignment factor of this picture descriptor.

    - #### setTransferCharacteristic

          void setTransferCharacteristic(AUID transferCharacteristic)

      Sets the opto-electronic transfer characteristic of this digital image descriptor.

      The default value for the transfer characteristic property is unspecified, which is represented by this property being omitted. If this method is called with a `null` value, the this optional property is omitted.

      Parameters:
        `transferCharacteristic` - Opto-electronic transfer characteristic of the picture descriptor.
      See Also:
        `TransferCharacteristicType`, `TypeDefinitions.TransferCharacteristicType`

    - #### getTransferCharacteristic

          AUID getTransferCharacteristic()
                                  throws PropertyNotPresentException

      Returns the opto-electronic transfer characteristic of this digital image descriptor. If this optional property is omitted, the opto-electronic characteristic is unspecified.

      Returns:
        Opto-electronic transfer characteristic of this digital image descriptor.
      Throws:
        `PropertyNotPresentException` - The optional opto-electronic characteristic of this picture descriptor is not present and so is unspecified.
      See Also:
        `TransferCharacteristicType`, `TypeDefinitions.TransferCharacteristicType`

    - #### setCodingEquations

          void setCodingEquations(AUID codingEquations)

      Sets the coding equations property of this picture descriptor, which specifies the coding equations to convert RGB image components to component color difference image components.

      The default value for this optional property is unspecified, which is represented by omitting this property. Setting the optional coding equations property to `null` will result in the property being omitted.

      Parameters:
        `codingEquations` - Coding equations property of this picture descriptor.
      See Also:
        `CodingEquationsType`, `TypeDefinitions.ColorPrimariesType`

    - #### getCodingEquations

          AUID getCodingEquations()
                           throws PropertyNotPresentException

      Returns the coding equations property of this picture descriptor, which specifies the coding equations to convert RGB image components to component color difference image components.

      The default value for this optional property is unspecified which is represented by this property being omitted.

      Returns:
        Coding equations property of this picture descriptor.
      Throws:
        `PropertyNotPresentException` - The optional coding equations property is not present for this picture descriptor, indicating that it is unspecified.
      See Also:
        `CodingEquationsType`, `TypeDefinitions.ColorPrimariesType`

    - #### setColorPrimaries

          void setColorPrimaries(AUID colorPrimaries)

      Sets the color primaries property for this picture descriptor.

      The default value for this property is unspecified, which is represented by omitting this property. Set this optional property to `null` to omit it.

      Parameters:
        `colorPrimaries` - Color primaries for the digiral image descriptor.
      See Also:
        `ColorPrimariesType`, `TypeDefinitions.ColorPrimariesType`

    - #### getColorPrimaries

          AUID getColorPrimaries()
                          throws PropertyNotPresentException

      Returns the color primaries property for the picture descriptor.

      This is an optional property and if the property is omitted it is assumed to be unspecified.

      Returns:
        Color primaries for this picture descriptor.
      Throws:
        `PropertyNotPresentException` - The optional color primaries property is not present for this picture descriptor, indicating that it is unspecified.
      See Also:
        `ColorPrimariesType`, `TypeDefinitions.ColorPrimariesType`

    - #### setImageStartOffset

          void setImageStartOffset(@UInt32
                                   Integer imageStartOffset)

      Sets the image start offset property of this picture descriptor, which specifies the number of unused bytes at the start of each video field.

      Set this optional property to `null` to omit its value. The default value of this property is 0.

      Parameters:
        `imageStartOffset` - Image start offset of this picture descriptor.
      Throws:
        `IllegalArgumentException` - The given image start offset is negative.
      See Also:
        `IMAGESTARTOFFSET_DEFAULT`

    - #### getImageStartOffset

          @UInt32
          int getImageStartOffset()

      Returns the image start offset property of this picture descriptor, which specifies the number of unused bytes at the start of each video field.

      If this property value is omitted, its default value of 0 will be returned.

      Returns:
        Image start offset of this picture descriptor.
      See Also:
        `IMAGESTARTOFFSET_DEFAULT`

    - #### setImageEndOffset

          void setImageEndOffset(@UInt32
                                 Integer imageEndOffset)
                          throws IllegalArgumentException

      Sets the image end offset property of this picture descriptor, which specifies the number of unused bytes at the end of each video field.

      Set this optional property to `null` to omit its value. The default value of this property is 0.

      Parameters:
        `imageEndOffset` - Image end offset property of this picture descriptor.
      Throws:
        `IllegalArgumentException` - Cannot set the image end offset to a negative value for this picture descriptor.
      See Also:
        `IMAGEENDOFFSET_DEFAULT`

    - #### getImageEndOffset

          @UInt32
          int getImageEndOffset()

      Returns the field end offset property of this picture descriptor, which specifies the number of unused bytes at the end of each video field.

      If this property value is omitted, its default value of `IMAGEENDOFFSET_DEFAULT` will be returned.

      Returns:
        Field end offset property of this picture descriptor.
      See Also:
        `IMAGEENDOFFSET_DEFAULT`

    - #### setFieldDominance

          void setFieldDominance(FieldNumber fieldDominance)

      Sets the field dominance property of this picture descriptor, which specifies whether field 1 or field 2 is dominant in images composed of two interlaced fields.

      This is an optional property with no default value. Call this method with `null` to omit this property.

      Parameters:
        `fieldDominance` - Field dominance of this picture descriptor.

    - #### getFieldDominance

          FieldNumber getFieldDominance()
                                 throws PropertyNotPresentException

      Returns the field dominance property of this picture descriptor, which specifies whether field 1 or field 2 is dominant in images composed of two interlaced fields. This is an optional property with no default value.

      Returns:
        Field dominance of this picture descriptor.
      Throws:
        `PropertyNotPresentException` - The optional field dominance property is not present for this picture descriptor.

    - #### setDisplayF2Offset

          void setDisplayF2Offset(@Int32
                                  Integer displayF2Offset)
                           throws IllegalArgumentException

      Sets the display field 2 offset property of this picture descriptor. This value specifies a topness adjustment for the displayed picture. Valid values are 0 or 1.

      Set this optional property to `null` to omit its value. The default value of this property is 0.

      Parameters:
        `displayF2Offset` - Display field 2 offset property of this picture descriptor.
      Throws:
        `IllegalArgumentException` - The given display field 2 offset is not one of the valid values of 0 or 1.
      See Also:
        `DISPLAYF2OFFSET_DEFAULT`

    - #### getDisplayF2Offset

          @Int32
          int getDisplayF2Offset()

      Returns the display field 2 offset property of this picture descriptor. This value specifies a topness adjustment for the displayed picture. Valid values are 0 or 1.

      If this property value is omitted, its default value of 0 will be returned.

      Returns:
        Display field 2 offset property of this picture descriptor.
      See Also:
        `DISPLAYF2OFFSET_DEFAULT`

    - #### setStoredF2Offset

          void setStoredF2Offset(@Int32
                                 Integer storedF2Offset)
                          throws IllegalArgumentException

      Sets the stored field 2 offset property of this picture descriptor, which specifies a topness adjustment for the stored picture. Valid values are 0 or -1.

      Set this optional property to `null` to omit its value. The default value of this property is 0.

      Parameters:
        `storedF2Offset` - Stored field 2 offset property of this digital image descriptor.
      Throws:
        `IllegalArgumentException` - The given stored field 2 offset is not one of the valid values of 0 or -1.
      See Also:
        `STOREDF2OFFSET_DEFAULT`

    - #### getStoredF2Offset

          @Int32
          int getStoredF2Offset()

      Returns the stored field 2 offset property of this picture descriptor, which specifies a topness adjustment for the stored picture. Valid values are 0 or -1.

      This is an optional property and if it is omitted, the default value of 0 will be returned.

      Returns:
        Stored field 2 offset property of this digital image descriptor.
      See Also:
        `STOREDF2OFFSET_DEFAULT`

    - #### setActiveFormatDescriptor

          void setActiveFormatDescriptor(@UInt8
                                         Byte activeFormatDescriptor)
                                  throws IllegalArgumentException

      Sets the active format descriptor property for the picture descriptor, which specifies the desired framing of the content within the displayed image (4:3 in 16:9 etc.). The value exactly matches the "active_format" element defined by ETSI TS 102 154.

      To omit this optional property, call this method with `null`. When the property is not present, it is considered to be the same as its default value of "unspecified".

      Parameters:
        `activeFormatDescriptor` - Active format descriptor property for this picture descriptor.
      Throws:
        `IllegalArgumentException` - The active format descriptor is a 4-bit value and cannot lie outside the range 0 to 15.

    - #### getActiveFormatDescriptor

          @UInt8
          byte getActiveFormatDescriptor()
                                         throws PropertyNotPresentException

      Returns the active format descriptor property for the picture descriptor, which specifies the desired framing of the content within the displayed image (4:3 in 16:9 etc.). The value exactly matches the active_format element defined by ETSI TS 102 154.

      This optional property is set to the default value of "unspecified" by omitting its value.

      Returns:
        Active format descriptor property for the picture descriptor.
      Throws:
        `PropertyNotPresentException` - The optional active format descriptor property is not present in this picture descriptor.

    - #### setSignalStandard

          void setSignalStandard(SignalStandardType signalStandard)

      Sets the signal standard property of this picture descriptor, which specifies the underlying signal standard used to define the raster.

      The default value for signal standard property is unspecified, which is represented by omitting this property. Set this optional property to `null` to omit it.

      Parameters:
        `signalStandard` - Signal standard property of this picture descriptor.

    - #### getSignalStandard

          SignalStandardType getSignalStandard()
                                        throws PropertyNotPresentException

      Returns the signal standard property of this picture descriptor. This property specifies the underlying signal standard used to define the raster.

      The default value for this property is unspecified, which is represented by omitting this property.

      Returns:
        Signal standard property of this picture descriptor.
      Throws:
        `PropertyNotPresentException` - The optional signal standard property is not present for this picture descriptor, indicating that it is unspecified.
      See Also:
        `SignalStandardType`

    - #### areDisplayValuesPresent

          boolean areDisplayValuesPresent()

      Returns whether this picture descriptor contains a display view. A value of `true` indicates that display height, width, x-offset and y-offset values are present.

      Returns:
        Does this picture descriptor contain display size and offset information?
      See Also:
        `getDisplayView()`, `setDisplayView(int, int, int, int)`

    - #### areSampledValuesPresent

          boolean areSampledValuesPresent()

      Returns whether this picture descriptor contains a sample area values dimensions and offsets. A value of `true` indicates that sampled height, width, x-offset and y-offset values are present.

      Returns:
        Does this picture descriptor contain sample area values and dimensions?
      See Also:
        `getSampledView()`, `setSampledView(int, int, int, int)`

    - #### clone

          PictureDescriptor clone()

      Create a cloned copy of this picture descriptor.

      Specified by:
        `clone` in interface `AAFFileDescriptor`
      Specified by:
        `clone` in interface `EssenceDescriptor`
      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Returns:
        Cloned copy of this picture descriptor.

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.