class P1::CameraSdk::IStoredImageHandle
Overview
Lightweight representation of an image file in the camera. More…
#include <C_P1CameraCommonStructs.h> class IStoredImageHandle { 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; }; // direct descendants class StoredImageHandleImpl;
Detailed Documentation
Lightweight representation of an image file in the camera.
This class is the interface to image files returned by the camera. It is lightweight and contains only a limited set of image metadata. It has no actual image bitmap data.
You use this image item ‘s id to query for extra info about an image or the fetch preview or tiles of the image. You can also request the entire IIQ file!
Version 3.0
See also:
P1::CameraSdk::Camera::AllImages
Methods
virtual uint32_t Id() const = 0
Gets the id of this image. Can change after a camera reboot or a storage swap.
virtual uint32_t Date() const = 0
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 = 0
Gets the filename of the image’s IIQ file.
virtual DeviceMask Device() const = 0
Gets a bitmask defining on what devices (XQS/SD), the image is stored.
virtual std::string DeviceString() const = 0
Device() in a string format.
virtual void RequestBasicImageInfoAsync() const = 0
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:
virtual std::shared_ptr<IImageFileBasicInfo const> BasicImageInfo(uint32_t const timeoutMs = 0) const = 0
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:
virtual bool RequestImageAsync() const = 0
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:
virtual void RequestPreviewAsync(ImageFormat const fileFormat = ImageFormat::RGB24) const = 0
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:
virtual std::shared_ptr<IPreview const> Preview( ImageFormat const fileFormat = ImageFormat::RGB24, uint32_t const timeoutMs = 0 ) const = 0
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 = 0
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:
virtual std::shared_ptr<ITile const> Tile( TileRequest const& tileRequest, uint32_t timeoutMs = 0 ) const = 0
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:
virtual void DeleteImage() = 0
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) = 0
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 |