PFrame Class Reference

Detailed Description

The PFrame class represents any 2D-image (RGB, gray-scale, ...) with a container of additional data pertaining to that image.

Each frame has a unique source-id (PGuid). This can be used to relate back to the original capture source for that image (e.g. camera, file-location).

The frame can also be given a unique-id (PGuid) which can be used to track its progress through any processing chain.

Also, any other data can be stored with the image using the PProperties container attached. For example this could be used to include frame number, time-stamp, GPS location, etc.

An important part of this interface is the way GetImage works. When constructing a PFrame the PImage can be any supported PImage::EPixelFormat in Papillon. When you request an image using the GetImage function if the current instance is not holding an image of that type it will try to convert it to the right type and return it. That instance will then store that type as a property. The next time you request an image of that image-type the cached version will be returned. To remove theses additional images from properties, use InvalidateCache().

Definition at line 50 of file PFrame.h.

#include <PFrame.h>

Constructor & Destructor Documentation

◆ PFrame() [1/3]

PFrame::PFrame ( )

Constructs an empty frame.

◆ PFrame() [2/3]

PFrame::PFrame ( const PImage image,
const PGuid frameId = PGuid::Null(),
const PGuid sourceId = PGuid::Null() 
)

Constructs a frame from any PImage.

◆ PFrame() [3/3]

PFrame::PFrame ( const PFrame other)

Constructs a shared copy of other.

See also
ShallowCopy()

◆ ~PFrame()

virtual PFrame::~PFrame ( )
virtual

Destroys this object.

Member Function Documentation

◆ ConvertTo()

void PFrame::ConvertTo ( PImage::EPixelFormat  format)

Converts this frame to the specified format.

The original image is lost.

◆ Crop()

PResult PFrame::Crop ( const PRectanglei r)

Crops this frame to the specified rectangle.

Returns PResult::C_OK if success, another result otherwise.

◆ Display()

PResult PFrame::Display ( const PString title,
papillon::int32  waitTimeMs = 0 
) const

Displays the image attached with this frame into a window with the specified title (for debug purpose), and waits for a key event infinitely when waitTimeMs < 0, or for delay milliseconds, when it is positive.

Returns PResult::C_OK if success, another result otherwise.

◆ DisplayScaled() [1/2]

PResult PFrame::DisplayScaled ( const PString title,
papillon::int32  width,
papillon::int32  height,
papillon::int32  waitTimeMs = 0 
) const

Displays the image attached with this frame into a window with the specified title and the specified size (a resize is performed if necessary) (for debug purpose), and waits for a key event infinitely when waitTimeMs < 0, or for delay milliseconds, when it is positive.

If width and height are <= 0, then resolution of the primary screen will be used.

Returns PResult::C_OK if success, another result otherwise.

◆ DisplayScaled() [2/2]

PResult PFrame::DisplayScaled ( const PString title,
papillon::int32  waitTimeMs = 0 
) const

Displays the image attached with this frame into a window at the size of the screen (primary monitor) (for debug purpose), and waits for a key event infinitely when waitTimeMs < 0, or for delay milliseconds, when it is positive.

Returns PResult::C_OK if success, another result otherwise.

◆ GetFrameId()

const PGuid& PFrame::GetFrameId ( ) const

Returns the global id associated with this frame.

◆ GetFrameNumber()

papillon::int32 PFrame::GetFrameNumber ( ) const

Returns the frame number associated with this frame (automatic frame numbering; does not depend on video source frame numbers) Typically, you will get consecutive frame numbers when using PInputVideoStream::GetFrame().

See also
GetSourceFrameNumber()

◆ GetHeight()

papillon::int32 PFrame::GetHeight ( ) const

Returns the height of this frame (number of rows), in pixels.

◆ GetImage()

const PImage& PFrame::GetImage ( ) const

Returns the image associated with this frame (read-only).

No image copy performed (PImage behaves like a smart pointer).

Warning: if you perform any changes on this image, you should call InvalidateCache() to be sure that images generated from this master image becomes unavailable from this frame.

◆ GetImageShared() [1/2]

PImage PFrame::GetImageShared ( ) const

Returns a shared instance of the image associated with this frame.

No image copy performed (PImage behaves like a smart pointer).

Warning: if you perform any changes on this image, you should call InvalidateCache() to be sure that images generated from this master image becomes unavailable from this frame.

◆ GetImageShared() [2/2]

PImage PFrame::GetImageShared ( PImage::EPixelFormat  pixelFormat) const

Returns a shared instance of the image associated with this frame, in the specified format.

Notes:

  • Lazy evaluation: the specified image is generated from the source image contained in the frame only if required, and not yet available. Once computed, the image is kept as a property so you can retrieve this image again for free.
  • No image copy performed.

◆ GetProperties()

const PProperties& PFrame::GetProperties ( ) const

Returns the properties associated with this image (read-only).

◆ GetPropertiesShared()

PProperties PFrame::GetPropertiesShared ( ) const

Returns a shared instance of properties associated with this image.

Can be used to store additional data associated with this image, like "deviceId" (PGuid), "captureTime" (PDateTime), "gpsLocation", etc. WARNING: the returned container offers direct read/write access; if you remove a property from this container, it will be removed from the frame.

◆ GetRectangle()

PRectanglei PFrame::GetRectangle ( ) const

Gets image rectangle: (0, 0, width, height).

◆ GetSize()

PSizei PFrame::GetSize ( ) const

Sets the plugin used to read this frame.

Returns the size of this frame (width x height), in pixels.

◆ GetSourceFrameNumber()

papillon::int32 PFrame::GetSourceFrameNumber ( ) const

Returns the frame number associated with this frame by the input video source is any, -1 otherwise; it might be different from GetFrameNumber() which use automatic numbering.

See also
GetFrameNumber()

◆ GetSourceId()

const PGuid& PFrame::GetSourceId ( ) const

Returns the global id associated with the source which generated this frame.

◆ GetTimestampUTC()

PDateTime PFrame::GetTimestampUTC ( ) const

Returns the timestamp associated with this frame, in UTC.

◆ GetWidth()

papillon::int32 PFrame::GetWidth ( ) const

Returns the width of this frame (number of columns), in pixels.

◆ InvalidateCache()

void PFrame::InvalidateCache ( )

Invalidates the cache associated with this frame: all images generated from the master image handled by this frame will be removed.

◆ operator=()

PFrame& PFrame::operator= ( const PFrame other)

Performs a shared copy of other to this object.

See also
ShallowCopy()

◆ Reset()

void PFrame::Reset ( )

Resets this frame.

Remove the image associated with this frame.

◆ Resize() [1/2]

void PFrame::Resize ( const PSizei newSize,
PImage::EAspectRatioMode  aspectRatioMode = PImage::E_IGNORE_ASPECT_RATIO,
PImage::EInterpolation  interpolation = PImage::E_INTERPOLATION_LINEAR 
)

Resizes this frame to the new size using the specified interpolation algorithm.

By default, do not preserve aspect ratio (see EAspectRatioMode modes).

New image size must be in the range 0..16384 (MAX_IMAGE_SIZE). Dimensions are automatically clamped if outside the valid range.

Returns PResult::C_OK if success, another result otherwise.

◆ Resize() [2/2]

void PFrame::Resize ( float  scaleFactor,
PImage::EInterpolation  interpolation = PImage::E_INTERPOLATION_LINEAR 
)

Resizes this frame using the specified scale factor and an interpolation algorithm.

New image size must be in the range 0..16384 (MAX_IMAGE_SIZE). Dimensions are automatically clamped if outside the valid range.

Returns PResult::C_OK if success, another result otherwise.

◆ SetFrameId()

void PFrame::SetFrameId ( const PGuid guid)

Returns the plugin used to read this frame if any or an empty string otherwise.

Sets the frame id associated with this frame.

◆ SetFrameNumber()

void PFrame::SetFrameNumber ( papillon::int32  frameNumber)

Sets the frame number associated with this frame.

◆ SetImage()

void PFrame::SetImage ( const PImage image)

Sets the image contained in this frame and invalidate images (cache) related to this image (other version of this image in different format).

Do not change current properties, frameId or sourceId.

◆ SetNewImage()

void PFrame::SetNewImage ( const PImage image,
const PGuid frameId = PGuid::Null(),
const PGuid sourceId = PGuid::Null() 
)

Sets the image contained in this frame and clears the containers of additional properties.

◆ SetProperties()

void PFrame::SetProperties ( const PProperties properties)

Replaces the properties container handle by this frame with the specified one.

◆ SetSourceFrameNumber()

void PFrame::SetSourceFrameNumber ( papillon::int32  frameNumber)

Sets the frame number associated with this frame, directly coming from the video source, if any.

◆ SetSourceId()

void PFrame::SetSourceId ( const PGuid guid)

Sets the global id associated with the source which generated this frame.

◆ SetTimestampToCurrentUTC()

void PFrame::SetTimestampToCurrentUTC ( )

Sets the timestamp associated with this frame to current UTC time, as reported by the system clock.

◆ SetTimestampUTC()

void PFrame::SetTimestampUTC ( const PDateTime timestamp)

Sets the timestamp associated with this frame, in UTC.

The specified timestamp is automatically converted to UTC.