CBLCameraLiveViewFrame

Objective-C

@protocol CBLCameraLiveViewFrame <NSObject, NSCopying>

Swift

protocol LiveViewFrame : NSCopying, NSObjectProtocol

Represents a single frame of a streaming live view image, along with any associated metadata.

  • Returns the date and time at which this frame was generated.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nonnull) NSDate *dateProduced;

    Swift

    var dateProduced: Date { get }

  • Returns an array of numbers representing the brigtness plane of the image’s histogram, or nil if not available.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSArray *brightnessHistogramPlane;

    Swift

    var brightnessHistogramPlane: [Any]? { get }

  • Returns an array of numbers representing the red plane of the image’s histogram, or nil if not available.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSArray *redHistogramPlane;

    Swift

    var redHistogramPlane: [Any]? { get }

  • Returns an array of numbers representing the green plane of the image’s histogram, or nil if not available.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSArray *greenHistogramPlane;

    Swift

    var greenHistogramPlane: [Any]? { get }

  • Returns an array of numbers representing the blue plane of the image’s histogram, or nil if not available.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSArray *blueHistogramPlane;

    Swift

    var blueHistogramPlane: [Any]? { get }

  • Returns the logical orientation of the frame.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLCameraLiveViewFrameOrientation orientation;

    Swift

    var orientation: LiveViewFrameOrientation { get }

  • Returns the angle as detected by the camera’s gyros, if available. 0.0 is perfectly level in the “normal” landscape orientation. Range is 0-359.9°.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGFloat rollAngle;

    Swift

    var rollAngle: CGFloat { get }

  • Returns the raw image data for the frame. See the rawPixelFormat and rawPixelFormatDescription properties for detailed information on the pixel format.

    It may be necessary to crop this image to avoid black bars. See rawPixelCropRect. It may be neccessary to resize this image to avoid distortion. See naturalImageSize.

    Note

    While the pixel format is usually stable once a live view stream starts, some cameras can change pixel formats mid-stream. It’s important to be able to handle this if you’re working directly with the various rawPixel… properties.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nonnull) NSData *rawPixelData;

    Swift

    var rawPixelData: Data { get }

  • Returns the broad pixel format of the data in the rawPixelData property. If the value is a raw pixel buffer, see the rawPixelFormatDescription for additional details.

    Note

    While this is usually stable once a live view stream starts, some cameras can change pixel formats mid-stream. It’s important to be able to handle this if you’re working directly with the various rawPixel… properties.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLCameraLiveViewFramePixelFormat rawPixelFormat;

    Swift

    var rawPixelFormat: LiveViewFramePixelFormat { get }

  • Returns the detailed pixel format of the data in the rawPixelData property.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nonnull) CMFormatDescriptionRef rawPixelFormatDescription;

    Swift

    var rawPixelFormatDescription: CMFormatDescription { get }

  • Returns the size of the image contained in the rawPixelData property, in pixels.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGSize rawPixelSize;

    Swift

    var rawPixelSize: CGSize { get }

  • Returns the rectangle with which to crop the image contained in rawPixelData to avoid black bars. It may also be neccessary to resize the image after cropping at the render site to avoid distortion. See naturalImageSize for details.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGRect rawPixelCropRect;

    Swift

    var rawPixelCropRect: CGRect { get }

  • Returns an NSImage or UIImage for this live view frame. Any required pixel format conversion and cropping will be applied for you. Due to this, the pixel size of this image may be different to the value of rawPixelSize. It may be neccessary to resize this image at the render site to avoid distortion. See naturalImageSize for details.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nullable) UIImage *image;

    Swift

    var image: UIImage? { get }

  • Returns the live view frame’s “natural” image size - i.e., the size at which it should be rendered to appear correctly. Usually, this is the same as the rawPixelCropRect property’s size value (and the image property’s size value), but in some cases cameras can deliver distorted images due to factors such as (for e.g.) line skipping.

    If this value is different to the aforementioned size values, the image needs to be resized by the client (i.e., you) in order to render correctly to the user.

    Due to the performance implications of this operation, it is highly recommended that this is done at the UI level so it can be performed by the device’s GPU. An example of this would be setting a view’s aspect ratio based on this value, then having it stretch its contents to fit.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGSize naturalImageSize;

    Swift

    var naturalImageSize: CGSize { get }

  • Returns YES if the frame’s naturalImageSize value is different to the size of the image delivered by the camera (including any crop rect), otherwise NO.

    If this value is YES, the frame’s image may need to be resized to not appear distorted. See naturalImageSize for details.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL requiresImageResizeToAvoidDistortion;

    Swift

    var requiresImageResizeToAvoidDistortion: Bool { get }

  • Returns the aspect in which the live view coordinate system is mapped. All values related to focus and zoom geometry returned by this class are relative to this property.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGSize aspect;

    Swift

    var aspect: CGSize { get }

  • Returns the areas defining the frame’s focusing rectangles, or an empty array if no focusing rectangles are available.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSArray<id<CBLCameraLiveViewAFArea>> *afAreas;

    Swift

    var afAreas: [any LiveViewAFArea]? { get }

  • Returns the rect defining the zoom preview rectangle (that is, a preview of the part of the image that will be seen if live view is zoomed in), or CGRectZero if this isn’t available.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGRect zoomPreviewRect;

    Swift

    var zoomPreviewRect: CGRect { get }

  • Returns the smallest crop size supported by the live view stream, or CGRectZero if not available.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGSize minimumCropSize;

    Swift

    var minimumCropSize: CGSize { get }

  • Defines rect of this frame’s image relative to the aspect. When zoomed out, this will typically be the a rectangle the same size as the frame’s aspect with a zero origin. When zoomed in, this defines a subrect inside that aspect that defines where the zoomed-in image is compared to the whole frame.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGRect imageFrameInAspect;

    Swift

    var imageFrameInAspect: CGRect { get }

  • Returns YES if the live view frame is “zoomed in” (that is, the imageFrameInAspect property is smaller than aspect.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isZoomedIn;

    Swift

    var isZoomedIn: Bool { get }

  • Translates the given rect inside the receiver’s aspect to a rect inside the target container. Useful for translating live view rects into views, for example.

    Declaration

    Objective-C

    - (CGRect)translateSubRectOfAspect:(CGRect)liveViewRect
                   toSubRectOfRect:(CGRect)targetContainer;

    Swift

    func translateSubRectOfAspect(_ liveViewRect: CGRect, toSubRectOf targetContainer: CGRect) -> CGRect

    Parameters

    liveViewRect

    The rect inside the receiver’s aspect.
    targetContainer

    The rect defining the bounds of the target container.

    Return Value

    The rect representing liveViewRect inside targetContainer.

  • Translates the given point inside the receiver’s aspect to a point inside the target container. Useful for translating live view points into views, for example.

    Declaration

    Objective-C

    - (CGPoint)translatePointInAspect:(CGPoint)liveViewPoint
                    toPointInRect:(CGRect)targetContainer;

    Swift

    func translatePointInAspect(_ liveViewPoint: CGPoint, toPointIn targetContainer: CGRect) -> CGPoint

    Parameters

    liveViewPoint

    The pont inside the receiver’s aspect.
    targetContainer

    The rect defining the bounds of the target container.

    Return Value

    The point representing liveViewPoint inside targetContainer.

  • Translates the given point inside the given rect into a point inside the receiver’s aspect. Useful for translating a point in a view into the live view aspect, for example.

    Declaration

    Objective-C

    - (CGPoint)pointInAspectTranslatedFromPoint:(CGPoint)point
                                     inRect:(CGRect)container;

    Swift

    func pointInAspectTranslated(from point: CGPoint, in container: CGRect) -> CGPoint

    Parameters

    point

    The pont to translate.
    container

    The rect defining the bounds of the container containing point.

    Return Value

    The point representing point inside the receiver’s aspect.