Jetson Inference
DNN Vision Library

Loading and saving image files from disk. More...

Classes

class  imageLoader
 Load an image or set of images from disk into GPU memory. More...
 
class  imageWriter
 Save an image or set of images to disk. More...
 

Functions

template<typename T >
bool loadImage (const char *filename, T **ptr, int *width, int *height)
 Load a color image from disk into CUDA memory, in uchar3/uchar4/float3/float4 formats with pixel values 0-255. More...
 
bool loadImage (const char *filename, void **output, int *width, int *height, imageFormat format)
 Load a color image from disk into CUDA memory, in uchar3/uchar4/float3/float4 formats with pixel values 0-255. More...
 
bool loadImageRGBA (const char *filename, float4 **ptr, int *width, int *height)
 Load a color image from disk into CUDA memory with alpha, in float4 RGBA format with pixel values 0-255. More...
 
bool loadImageRGBA (const char *filename, float4 **cpu, float4 **gpu, int *width, int *height)
 Load a color image from disk into CUDA memory with alpha, in float4 RGBA format with pixel values 0-255. More...
 
template<typename T >
bool saveImage (const char *filename, T *ptr, int width, int height, int quality=95, const float2 &pixel_range=make_float2(0, 255), bool sync=true)
 Save an image in CPU/GPU shared memory to disk. More...
 
bool saveImage (const char *filename, void *ptr, int width, int height, imageFormat format, int quality=95, const float2 &pixel_range=make_float2(0, 255), bool sync=true)
 Save an image in CPU/GPU shared memory to disk. More...
 
bool saveImageRGBA (const char *filename, float4 *ptr, int width, int height, float max_pixel=255.0f, int quality=100)
 Save a float4 image in CPU/GPU shared memory to disk. More...
 

Detailed Description

Loading and saving image files from disk.


Class Documentation

◆ imageLoader

class imageLoader

Load an image or set of images from disk into GPU memory.

Supported image formats for loading are JPG, PNG, TGA, BMP, GIF, PSD, HDR, PIC, and PNM (PPM/PGM binary). Internally, imageLoader uses the loadImage() function to load the images, so the supported formats are the same.

imageLoader has the ability to load an sequence of images from a directory, including wildcard characters (e.g. images/*.jpg), or just a single image. When given just the path to a directory, it will load all valid images from that directory.

Note
imageLoader implements the videoSource interface and is intended to be used through that as opposed to directly. videoSource implements additional command-line parsing of videoOptions to construct instances.
See also
videoSource
Inheritance diagram for imageLoader:
videoSource

Public Member Functions

virtual ~imageLoader ()
 Destructor. More...
 
virtual bool Capture (void **image, imageFormat format, uint64_t timeout=DEFAULT_TIMEOUT, int *status=NULL)
 Load the next frame. More...
 
virtual bool Open ()
 Open the stream. More...
 
virtual void Close ()
 Close the stream. More...
 
bool IsEOS () const
 Return true if End Of Stream (EOS) has been reached. More...
 
virtual uint32_t GetType () const
 Return the interface type (imageLoader::Type) More...
 
- Public Member Functions inherited from videoSource
virtual ~videoSource ()
 Destroy interface and release all resources. More...
 
template<typename T >
bool Capture (T **image, int *status)
 Capture the next image from the video stream, using the default timeout of 1000ms. More...
 
template<typename T >
bool Capture (T **image, uint64_t timeout=DEFAULT_TIMEOUT, int *status=NULL)
 Capture the next image from the video stream. More...
 
bool IsStreaming () const
 Check if the device is actively streaming or not. More...
 
uint32_t GetWidth () const
 Return the width of the stream, in pixels. More...
 
uint32_t GetHeight () const
 Return the height of the stream, in pixels. More...
 
uint32_t GetFrameRate () const
 Return the framerate, in Hz or FPS. More...
 
uint64_t GetFrameCount () const
 Return the number of frames captured. More...
 
uint64_t GetLastTimestamp () const
 Get timestamp of the last captured frame, in nanoseconds. More...
 
imageFormat GetRawFormat () const
 Get raw image format. More...
 
const URIGetResource () const
 Return the resource URI of the stream. More...
 
const videoOptionsGetOptions () const
 Return the videoOptions of the stream. More...
 
bool IsType (uint32_t type) const
 Check if this stream is of a particular type. More...
 
template<typename T >
bool IsType () const
 Check if a this stream is of a particular type. More...
 
const char * TypeToStr () const
 Convert this stream's class type to string. More...
 

Static Public Member Functions

static imageLoaderCreate (const char *path, const videoOptions &options=videoOptions())
 Create an imageLoader instance from a path and optional videoOptions. More...
 
static imageLoaderCreate (const videoOptions &options)
 Create an imageLoader instance from the provided video options. More...
 
static bool IsSupportedExtension (const char *ext)
 Return true if the extension is in the list of SupportedExtensions. More...
 
- Static Public Member Functions inherited from videoSource
static videoSourceCreate (const videoOptions &options)
 Create videoSource interface from a videoOptions struct that's already been filled out. More...
 
static videoSourceCreate (const char *URI, const videoOptions &options=videoOptions())
 Create videoSource interface from a resource URI string and optional videoOptions. More...
 
static videoSourceCreate (const char *URI, const commandLine &cmdLine)
 Create videoSource interface from a resource URI string and parsing command line arguments. More...
 
static videoSourceCreate (const char *URI, const int argc, char **argv)
 Create videoSource interface from a resource URI string and parsing command line arguments. More...
 
static videoSourceCreate (const int argc, char **argv, int positionArg=-1)
 Create videoSource interface by parsing command line arguments, including the resource URI. More...
 
static videoSourceCreate (const commandLine &cmdLine, int positionArg=-1)
 Create videoSource interface by parsing command line arguments, including the resource URI. More...
 
static const char * Usage ()
 Usage string for command line arguments to Create() More...
 
static const char * TypeToStr (uint32_t type)
 Convert a class type to a string. More...
 

Static Public Attributes

static const uint32_t Type = (1 << 4)
 Unique type identifier of imageLoader class. More...
 
static const char * SupportedExtensions []
 String array of supported image file extensions, terminated with a NULL sentinel value. More...
 
- Static Public Attributes inherited from videoSource
static const uint64_t DEFAULT_TIMEOUT =1000
 The default Capture timeout (1000ms) More...
 

Protected Member Functions

 imageLoader (const videoOptions &options)
 
bool isLooping () const
 
- Protected Member Functions inherited from videoSource
 videoSource (const videoOptions &options)
 

Protected Attributes

bool mEOS
 
size_t mLoopCount
 
size_t mNextFile
 
std::vector< std::string > mFiles
 
std::vector< void * > mBuffers
 
- Protected Attributes inherited from videoSource
bool mStreaming
 
videoOptions mOptions
 
uint64_t mLastTimestamp
 
imageFormat mRawFormat
 

Additional Inherited Members

- Public Types inherited from videoSource
enum  Status { ERROR = -2, EOS = -1, TIMEOUT = 0, OK = 1 }
 Stream status codes that are optionally returned from Capture() More...
 

Constructor & Destructor Documentation

◆ ~imageLoader()

virtual imageLoader::~imageLoader ( )
virtual

Destructor.

◆ imageLoader()

imageLoader::imageLoader ( const videoOptions options)
protected

Member Function Documentation

◆ Capture()

virtual bool imageLoader::Capture ( void **  image,
imageFormat  format,
uint64_t  timeout = DEFAULT_TIMEOUT,
int *  status = NULL 
)
virtual

Load the next frame.

See also
videoSource::Capture()

Implements videoSource.

◆ Close()

virtual void imageLoader::Close ( )
virtual

Close the stream.

See also
videoSource::Close()

Reimplemented from videoSource.

◆ Create() [1/2]

static imageLoader* imageLoader::Create ( const char *  path,
const videoOptions options = videoOptions() 
)
static

Create an imageLoader instance from a path and optional videoOptions.

◆ Create() [2/2]

static imageLoader* imageLoader::Create ( const videoOptions options)
static

Create an imageLoader instance from the provided video options.

◆ GetType()

virtual uint32_t imageLoader::GetType ( ) const
inlinevirtual

Return the interface type (imageLoader::Type)

Reimplemented from videoSource.

◆ IsEOS()

bool imageLoader::IsEOS ( ) const
inline

Return true if End Of Stream (EOS) has been reached.

In the context of imageLoader, EOS means that all images in the sequence have been loaded, and looping is either disabled or all loops have already been run.

◆ isLooping()

bool imageLoader::isLooping ( ) const
inlineprotected

◆ IsSupportedExtension()

static bool imageLoader::IsSupportedExtension ( const char *  ext)
static

Return true if the extension is in the list of SupportedExtensions.

Parameters
extstring containing the extension to be checked (should not contain leading dot)
See also
SupportedExtensions for the list of supported Video Streaming file extensions.

◆ Open()

virtual bool imageLoader::Open ( )
virtual

Open the stream.

See also
videoSource::Open()

Reimplemented from videoSource.

Member Data Documentation

◆ mBuffers

std::vector<void*> imageLoader::mBuffers
protected

◆ mEOS

bool imageLoader::mEOS
protected

◆ mFiles

std::vector<std::string> imageLoader::mFiles
protected

◆ mLoopCount

size_t imageLoader::mLoopCount
protected

◆ mNextFile

size_t imageLoader::mNextFile
protected

◆ SupportedExtensions

const char* imageLoader::SupportedExtensions[]
static

String array of supported image file extensions, terminated with a NULL sentinel value.

The supported extension are:

  • JPG / JPEG
  • PNG
  • TGA / TARGA
  • BMP
  • GIF
    • PSD
  • HDR
  • PIC
  • PNM / PBM / PPM / PGM
See also
IsSupportedExtension() to check a string against this list.

◆ Type

const uint32_t imageLoader::Type = (1 << 4)
static

Unique type identifier of imageLoader class.

◆ imageWriter

class imageWriter

Save an image or set of images to disk.

Supported image formats for saving are JPG, PNG, TGA, and BMP. Internally, imageLoader uses the saveImage() function to save the images, so the supported formats are the same.

imageWriter has the ability to write a sequence of images to a directory, for example images/i.jpg (where i becomes the image number), or just a single image with a static filename (e.g. images/my_image.jpg). When given just the path of a directory as output, it will default to incremental i.jpg sequencing and save in JPG format.

Note
imageWriter implements the videoOutput interface and is intended to be used through that as opposed to directly. videoOutput implements additional command-line parsing of videoOptions to construct instances.
See also
videoOutput
Inheritance diagram for imageWriter:
videoOutput

Public Member Functions

virtual ~imageWriter ()
 Destructor. More...
 
template<typename T >
bool Render (T *image, uint32_t width, uint32_t height)
 Save the next frame. More...
 
virtual bool Render (void *image, uint32_t width, uint32_t height, imageFormat format)
 Save the next frame. More...
 
virtual uint32_t GetType () const
 Return the interface type (imageWriter::Type) More...
 
- Public Member Functions inherited from videoOutput
virtual ~videoOutput ()
 Destroy interface and release all resources. More...
 
template<typename T >
bool Render (T *image, uint32_t width, uint32_t height)
 Render and output the next frame to the stream. More...
 
virtual bool Open ()
 Begin streaming the device. More...
 
virtual void Close ()
 Stop streaming the device. More...
 
bool IsStreaming () const
 Check if the device is actively streaming or not. More...
 
uint32_t GetWidth () const
 Return the width of the stream, in pixels. More...
 
uint32_t GetHeight () const
 Return the height of the stream, in pixels. More...
 
float GetFrameRate () const
 Return the framerate, in Hz or FPS. More...
 
uint64_t GetFrameCount () const
 Return the number of frames output. More...
 
const URIGetResource () const
 Return the resource URI of the stream. More...
 
const videoOptionsGetOptions () const
 Return the videoOptions of the stream. More...
 
void AddOutput (videoOutput *output)
 Add an output sub-stream. More...
 
uint32_t GetNumOutputs () const
 Return the number of sub-streams. More...
 
videoOutputGetOutput (uint32_t index) const
 Return a sub-stream. More...
 
virtual void SetStatus (const char *str)
 Set a status string (i.e. More...
 
bool IsType (uint32_t type) const
 Check if this stream is of a particular type. More...
 
template<typename T >
bool IsType () const
 Check if a this stream is of a particular type. More...
 
const char * TypeToStr () const
 Convert this stream's class type to string. More...
 

Static Public Member Functions

static imageWriterCreate (const char *path, const videoOptions &options=videoOptions())
 Create an imageWriter instance from a path and optional videoOptions. More...
 
static imageWriterCreate (const videoOptions &options)
 Create an imageWriter instance from the provided video options. More...
 
static bool IsSupportedExtension (const char *ext)
 Return true if the extension is in the list of SupportedExtensions. More...
 
- Static Public Member Functions inherited from videoOutput
static videoOutputCreate (const videoOptions &options)
 Create videoOutput interface from a videoOptions struct that's already been filled out. More...
 
static videoOutputCreate (const char *URI, const videoOptions &options=videoOptions())
 Create videoOutput interface from a resource URI string and optional videoOptions. More...
 
static videoOutputCreate (const char *URI, const commandLine &cmdLine)
 Create videoOutput interface from a resource URI string and parsing command line arguments. More...
 
static videoOutputCreate (const char *URI, const int argc, char **argv)
 Create videoOutput interface from a resource URI string and parsing command line arguments. More...
 
static videoOutputCreate (const int argc, char **argv, int positionArg=-1)
 Create videoOutput interface by parsing command line arguments, including the resource URI. More...
 
static videoOutputCreate (const commandLine &cmdLine, int positionArg=-1)
 Create videoOutput interface by parsing command line arguments, including the resource URI. More...
 
static videoOutputCreateNullOutput ()
 Create videoOutput interface that acts as a NULL output and does nothing with incoming frames. More...
 
static const char * Usage ()
 Usage string for command line arguments to Create() More...
 
static const char * TypeToStr (uint32_t type)
 Convert a class type to a string. More...
 

Static Public Attributes

static const uint32_t Type = (1 << 5)
 Unique type identifier of imageWriter class. More...
 
static const char * SupportedExtensions []
 String array of supported image file extensions, terminated with a NULL sentinel value. More...
 

Protected Member Functions

 imageWriter (const videoOptions &options)
 
- Protected Member Functions inherited from videoOutput
 videoOutput (const videoOptions &options)
 

Protected Attributes

uint32_t mFileCount
 
char mFileOut [1024]
 
- Protected Attributes inherited from videoOutput
bool mStreaming
 
videoOptions mOptions
 
std::vector< videoOutput * > mOutputs
 

Constructor & Destructor Documentation

◆ ~imageWriter()

virtual imageWriter::~imageWriter ( )
virtual

Destructor.

◆ imageWriter()

imageWriter::imageWriter ( const videoOptions options)
protected

Member Function Documentation

◆ Create() [1/2]

static imageWriter* imageWriter::Create ( const char *  path,
const videoOptions options = videoOptions() 
)
static

Create an imageWriter instance from a path and optional videoOptions.

◆ Create() [2/2]

static imageWriter* imageWriter::Create ( const videoOptions options)
static

Create an imageWriter instance from the provided video options.

◆ GetType()

virtual uint32_t imageWriter::GetType ( ) const
inlinevirtual

Return the interface type (imageWriter::Type)

Reimplemented from videoOutput.

◆ IsSupportedExtension()

static bool imageWriter::IsSupportedExtension ( const char *  ext)
static

Return true if the extension is in the list of SupportedExtensions.

Parameters
extstring containing the extension to be checked (should not contain leading dot)
See also
SupportedExtensions for the list of supported Video Streaming file extensions.

◆ Render() [1/2]

template<typename T >
bool imageWriter::Render ( T *  image,
uint32_t  width,
uint32_t  height 
)
inline

Save the next frame.

See also
videoOutput::Render()

◆ Render() [2/2]

virtual bool imageWriter::Render ( void *  image,
uint32_t  width,
uint32_t  height,
imageFormat  format 
)
virtual

Save the next frame.

See also
videoOutput::Render()

Reimplemented from videoOutput.

Member Data Documentation

◆ mFileCount

uint32_t imageWriter::mFileCount
protected

◆ mFileOut

char imageWriter::mFileOut[1024]
protected

◆ SupportedExtensions

const char* imageWriter::SupportedExtensions[]
static

String array of supported image file extensions, terminated with a NULL sentinel value.

The supported extension are:

  • JPG / JPEG
  • PNG
  • TGA / TARGA
  • BMP
See also
IsSupportedExtension() to check a string against this list.

◆ Type

const uint32_t imageWriter::Type = (1 << 5)
static

Unique type identifier of imageWriter class.

Function Documentation

◆ loadImage() [1/2]

template<typename T >
bool loadImage ( const char *  filename,
T **  ptr,
int *  width,
int *  height 
)

Load a color image from disk into CUDA memory, in uchar3/uchar4/float3/float4 formats with pixel values 0-255.

Supported image file formats by loadImage() include:

  • JPG
  • PNG
  • TGA
  • BMP
  • GIF
  • PSD
  • HDR
  • PIC
  • PNM (PPM/PGM binary)

This function loads the image into shared CPU/GPU memory, using the functions from cudaMappedMemory.h

Parameters
[in]filenamePath to the image file to load from disk.
[out]ptrReference to pointer that will be set to the shared CPU/GPU buffer containing the image that will be allocated. This buffer will be allocated by loadImage() in CUDA mapped memory, so it is shared between CPU/GPU. gpu will be the pointer to this shared buffer in the GPU's address space. There is physically one buffer in memory.
[in,out]widthPointer to int variable that gets set to the width of the image in pixels. If the width variable contains a non-zero value when it's passed in, the image is resized to this desired width. Otherwise if the value of width is 0, the image will be loaded with it's dimensions from the file on disk.
[in,out]heightPointer to int variable that gets set to the height of the image in pixels. If the height variable contains a non-zero value when it's passed in, the image is resized to this desired height. Otherwise if the value of height is 0, the image will be loaded with it's dimensions from the file on disk.

◆ loadImage() [2/2]

bool loadImage ( const char *  filename,
void **  output,
int *  width,
int *  height,
imageFormat  format 
)

Load a color image from disk into CUDA memory, in uchar3/uchar4/float3/float4 formats with pixel values 0-255.

Supported image file formats by loadImage() include:

  • JPG
  • PNG
  • TGA
  • BMP
  • GIF
  • PSD
  • HDR
  • PIC
  • PNM (PPM/PGM binary)

This function loads the image into shared CPU/GPU memory, using the functions from cudaMappedMemory.h

Parameters
[in]filenamePath to the image file to load from disk.
[out]ptrReference to pointer that will be set to the shared CPU/GPU buffer containing the image that will be allocated. This buffer will be allocated by loadImage() in CUDA mapped memory, so it is shared between CPU/GPU. gpu will be the pointer to this shared buffer in the GPU's address space. There is physically one buffer in memory.
[in,out]widthPointer to int variable that gets set to the width of the image in pixels. If the width variable contains a non-zero value when it's passed in, the image is resized to this desired width. Otherwise if the value of width is 0, the image will be loaded with it's dimensions from the file on disk.
[in,out]heightPointer to int variable that gets set to the height of the image in pixels. If the height variable contains a non-zero value when it's passed in, the image is resized to this desired height. Otherwise if the value of height is 0, the image will be loaded with it's dimensions from the file on disk.

◆ loadImageRGBA() [1/2]

bool loadImageRGBA ( const char *  filename,
float4 **  cpu,
float4 **  gpu,
int *  width,
int *  height 
)

Load a color image from disk into CUDA memory with alpha, in float4 RGBA format with pixel values 0-255.

See also
loadImage() for more details about parameters and supported Image I/O formats.
Deprecated:
this overload of loadImageRGBA() is deprecated and provided for legacy compatbility. having separate CPU and GPU pointers for shared memory is no longer needed, as they are the same. it is recommended to use loadImage() instead, which supports multiple image formats.

◆ loadImageRGBA() [2/2]

bool loadImageRGBA ( const char *  filename,
float4 **  ptr,
int *  width,
int *  height 
)

Load a color image from disk into CUDA memory with alpha, in float4 RGBA format with pixel values 0-255.

See also
loadImage() for more details about parameters and supported Image I/O formats.
Deprecated:
this overload of loadImageRGBA() is deprecated and provided for legacy compatbility. it is recommended to use loadImage() instead, which supports multiple image formats.

◆ saveImage() [1/2]

template<typename T >
bool saveImage ( const char *  filename,
T *  ptr,
int  width,
int  height,
int  quality = 95,
const float2 &  pixel_range = make_float2(0,255),
bool  sync = true 
)

Save an image in CPU/GPU shared memory to disk.

Supported image file formats by saveImage() include:

  • JPG
  • PNG
  • TGA
  • BMP
Parameters
filenameDesired path of the image file to save to disk.
ptrPointer to the buffer containing the image in shared CPU/GPU zero-copy memory.
widthWidth of the image in pixels.
heightHeight of the image in pixels.
max_pixelThe maximum pixel value of this image, by default it's 255 for images in the range of 0-255. If your image is in the range of 0-1, pass 1.0 as this value. Then the pixel values of the image will be rescaled appropriately to be stored on disk (which expects a range of 0-255).
qualityIndicates the compression quality level (between 1 and 100) to be applied for JPEG and PNG images. A level of 1 correponds to reduced quality and maximum compression. A level of 100 corresponds to maximum quality and reduced compression. By default a level of 95 is used for high quality and moderate compression. Note that this quality parameter only applies to JPEG and PNG, other formats will ignore it.
syncIf true (default), the GPU will be sychronized with cudaDeviceSynchronize() to assure that any processing on the image has been completed before saving it to disk.

◆ saveImage() [2/2]

bool saveImage ( const char *  filename,
void *  ptr,
int  width,
int  height,
imageFormat  format,
int  quality = 95,
const float2 &  pixel_range = make_float2(0, 255),
bool  sync = true 
)

Save an image in CPU/GPU shared memory to disk.

Supported image file formats by saveImage() include:

  • JPG
  • PNG
  • TGA
  • BMP
Parameters
filenameDesired path of the image file to save to disk.
ptrPointer to the buffer containing the image in shared CPU/GPU zero-copy memory.
widthWidth of the image in pixels.
heightHeight of the image in pixels.
max_pixelThe maximum pixel value of this image, by default it's 255 for images in the range of 0-255. If your image is in the range of 0-1, pass 1.0 as this value. Then the pixel values of the image will be rescaled appropriately to be stored on disk (which expects a range of 0-255).
qualityIndicates the compression quality level (between 1 and 100) to be applied for JPEG and PNG images. A level of 1 correponds to reduced quality and maximum compression. A level of 100 corresponds to maximum quality and reduced compression. By default a level of 95 is used for high quality and moderate compression. Note that this quality parameter only applies to JPEG and PNG, other formats will ignore it.
syncIf true (default), the GPU will be sychronized with cudaDeviceSynchronize() to assure that any processing on the image has been completed before saving it to disk.

◆ saveImageRGBA()

bool saveImageRGBA ( const char *  filename,
float4 *  ptr,
int  width,
int  height,
float  max_pixel = 255.0f,
int  quality = 100 
)

Save a float4 image in CPU/GPU shared memory to disk.

See also
saveImage() for more details about parameters and supported Image I/O formats.
Deprecated:
saveImageRGBA() is deprecated and provided for legacy compatbility. it is recommended to use saveImage() instead, which supports multiple image formats.