class P1::CameraSdk::StoredImageHandleImpl

Overview

#include <C_P1CameraPrivStructs.hpp>

class StoredImageHandleImpl: public P1::CameraSdk::IStoredImageHandle
{
public:
    // typedefs

    typedef P1::IQP::ImageEnumerationAgent::ImageListItem const PrivStructType;

    // construction

    StoredImageHandleImpl(PrivStructType*const dataStruct, CameraId const camId);
    StoredImageHandleImpl(PrivStructType& dataStruct, CameraId const camId);

    // methods

    virtual uint32_t Id() const;
    virtual uint32_t Date() const;
    virtual std::string const& Filename() const;
    virtual DeviceMask Device() const;
    virtual std::string DeviceString() const;
    virtual void RequestBasicImageInfoAsync() const;
    virtual std::shared_ptr<IImageFileBasicInfo const> BasicImageInfo(uint32_t const timeoutMs) const;
    virtual bool RequestImageAsync() const;
    virtual void RequestPreviewAsync(ImageFormat const fileFormat) const;

    virtual std::shared_ptr<IPreview const> Preview(
        ImageFormat const fileFormat,
        uint32_t const timeoutMs
        ) const;

    virtual void RequestTileAsync(TileRequest const& tileRequest) const;

    virtual std::shared_ptr<ITile const> Tile(
        TileRequest const& tileRequest,
        uint32_t timeoutMs
        ) const;

    virtual void DeleteImage();
    virtual void RateImage(IImageFileBasicInfo::StarRating const rating);
};

Inherited Members

public:
    // enums

    enum DeviceMask;

    // structs

    struct TileRequest;

    // methods

    virtual uint32_t Id() const = 0;
    virtual uint32_t Date() const = 0;
    virtual std::string const& Filename() const = 0;
    virtual DeviceMask Device() const = 0;
    virtual std::string DeviceString() const = 0;
    virtual void RequestBasicImageInfoAsync() const = 0;
    virtual std::shared_ptr<IImageFileBasicInfo const> BasicImageInfo(uint32_t const timeoutMs = 0) const = 0;
    virtual bool RequestImageAsync() const = 0;
    virtual void RequestPreviewAsync(ImageFormat const fileFormat = ImageFormat::RGB24) const = 0;

    virtual std::shared_ptr<IPreview const> Preview(
        ImageFormat const fileFormat = ImageFormat::RGB24,
        uint32_t const timeoutMs = 0
        ) const = 0;

    virtual void RequestTileAsync(TileRequest const& tileRequest) const = 0;

    virtual std::shared_ptr<ITile const> Tile(
        TileRequest const& tileRequest,
        uint32_t timeoutMs = 0
        ) const = 0;

    virtual void DeleteImage() = 0;
    virtual void RateImage(IImageFileBasicInfo::StarRating const rating) = 0;

Detailed Documentation

Methods

virtual uint32_t Id() const

Gets the id of this image. Can change after a camera reboot or a storage swap.

virtual uint32_t Date() const

Gets the capture date & time for this image. As a Unix Epoch timestamp. (Seconds since 1970-01-01 00:00:00 UTC.)

virtual std::string const& Filename() const

Gets the filename of the image’s IIQ file.

virtual DeviceMask Device() const

Gets a bitmask defining on what devices (XQS/SD), the image is stored.

virtual std::string DeviceString() const

Device() in a string format.

virtual void RequestBasicImageInfoAsync() const

Requests a set of commonly used meta data about the image.

CameraSDK defines a curated set of common meta data about an image called BasicImageInfo. See IImageFileBasicInfo for what meta data is is included.

The requested basic info object is returned by a notification. To retrieve the object, you must listen for the EventType::CameraImageBasicImageInfo notification, before calling this method.

Version 3.0

See also:

BasicImageInfo

virtual std::shared_ptr<IImageFileBasicInfo const> BasicImageInfo(uint32_t const timeoutMs) const

A blocking version of RequestBasicImageInfoAsync.

Version 3.0

Parameters:

timeoutMs

An optional maximum amount of milliseconds to wait for a basic info object, before giving up. Zero (0) is wait forever.

Returns:

A pointer to an IImageFileBasicInfo object or nullptr on timeout.

See also:

RequestBasicImageInfoAsync

virtual bool RequestImageAsync() const

Request a full IIQ file of the image.

This method triggers on-demand transfer of the entire IIQ file of an image. To retrieve the object, you must listen for the EventType::CameraImageReady notification, before calling this method. This notification contains the image via the FullImage() method.

The listener thread cannot know whether the arrived image is a just triggered capture, or a result of an on-demand request from this method. Therefore, use the IIQ filename to identify your requested image.

It is necessary to subscribe to image transfers via IFullImageSubscription for images to be transferred.

Version 3.0

See also:

IFullImageSubscription

virtual void RequestPreviewAsync(ImageFormat const fileFormat) const

Request the preview (thumbnail) for an image.

A preview is a scaled down version of the entire image, encoded as either a RGB bitmap or as an complete jpeg file. Depending on the requested fileFormat format, the camera might be able to use any existing preview (thumbnail) present inside the image’s IIQ file.

The RGB previews can be stored inside the IIQ files. This method returns the stored preview, if it exists, or generates a new one if not. If you ask for a Jpeg formatted preview, the generated or stored RGB preview is converted to Jpeg (on the camera), before being returned to you. Jpeg previews are not cached.

Jpegs are significantly smaller in file size, but time consuming to encode. Prefer Jpeg if you are connected to the camera over a slow connection, like an outdoor Wifi.

The dimensions of the preview is controlled by the camera.

The requested preview image object is returned by a notification. To retrieve the object, you must listen for the EventType::CameraPreviewReady notification, before calling this method.

Version 3.0

Parameters:

fileFormat

Optionally change encoding of the returned preview image. Default is RGB bitmap.

See also:

RequestTileAsync

virtual std::shared_ptr<IPreview const> Preview(
    ImageFormat const fileFormat,
    uint32_t const timeoutMs
    ) const

A blocking version of RequestPreviewAsync.

Version 3.0

Parameters:

fileFormat	Optionally change encoding of the returned preview image. Default is RGB bitmap.
timeoutMs	An optional maximum amount of milliseconds to wait for the preview, before giving up. Zero (0) is ‘wait forever’.

Returns:

A pointer to an image buffer that encapsulates the image data, or nullptr on timeout.

virtual void RequestTileAsync(TileRequest const& tileRequest) const

Request a tile : a (scaled) crop of the full image.

Tiles are a cropped and scaled jpeg encoded previews of the full image. The camera takes the requested crop of the image, scales it and, optionally, converts it to jpeg.

The crop is defined in full image coordinates, meaning the pixel range of the full (visible) image dimensions. Origo is upper left corner. Any scaling is applied after cropping, meaning that if the crop dimension is 100 px, scaling by 0.5 results in an output image that is ~50 px.

This method is asynchronous and will return immediately. The requested tile object is returned by a notification. To retrieve the object, you must listen for the EventType::CameraTileReady notification, before calling this method. Note that this notification EventType is shared with incoming previews.

Note that the camera might not (and will likely not), give the exact crop you requested. The resulting might differ a few pixels in offset or size. This is due performance optimizations in the image conversion pipeline. Speed is favoured over precision.

Version 3.0

Parameters:

tileRequest

Specification of requested tile.

See also:

RequestPreviewAsync

virtual std::shared_ptr<ITile const> Tile(
    TileRequest const& tileRequest,
    uint32_t timeoutMs
    ) const

A blocking version of RequestTileAsync.

Version 3.0

Parameters:

tileRequest	Specification of requested tile.
timeoutMs	To maximum time to wait for the camera to return the tile. Zero (0) is ‘wait forever’.

Returns:

A pointer to an image buffer that encapsulates the image data, or nullptr on timeout.

See also:

Preview

virtual void DeleteImage()

Delete an image from the camera storage.

This method deletes the image (IIQ file) and any associated Jpeg file, from either XQD or SD card storage. Deletion is irreversible.

Confirmation of delete request is provided by a notification. If you wish to receive this notification, you must listen for the EventType::CameraImageEnumElementRemoved notification, before calling this method. If the request fails, there is no notification.

Version 3.0

virtual void RateImage(IImageFileBasicInfo::StarRating const rating)

Change the star-rating of an image.

All images can have an optional star-rating, to mark them as more or less significant. Use this method to change an image rating, or remove it.

Confirmation of a changed rating is provided by a notification. If you wish to receive this notification, you must listen for the EventType::CameraImageEnumElementEdited notification, before calling this method. If the request fails, there is no notification.

To retrieve the existing star-rating of an image you should use the methods for retrieving all images on the camera, or the BasicImageInfo.

Version 3.0

Parameters:

rating

The new rating to set on the image