Difference between revisions of "Image I/O & Framework"

From CUVI Wiki
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
CUVI sdlksljfdks;dlks kdsldks
==Using CUVI with C++==
CUVI C++ interface uses various features of C++ including classes, namespaces, default arguments and overloading to provide ease of use.


==Using CUVI with C++==
CUVI C++ interface uses various features of C++ including classes, namespaces and default arguments to provide ease of use. User has the freedom to use C++ specifics as well as C features of CUVI while using C++ compiler however is restricted to C-only features if using a C compiler.
===CuviImage===
===CuviImage===
CuviImage is a C++ class to hold image data on the device. It has all the essential members to hold image information as well as methods to create and move image to and from device. All the C++ functions in CUVI take CuviImage as input/output image argument. CuviImage creates an image on the GPU so you do not need to cater for manually copying the image to the GPU and then back to the CPU, this is catered by CuviImage.
CuviImage is a C++ class to hold image data on the device. It has all the essential members to hold image information as well as methods to create and move image to and from device. All the C++ functions in CUVI take CuviImage as input/output image argument. CuviImage creates an image on the GPU so you do not need to cater for manually copying the image to the GPU and then back to the CPU, this is catered by CuviImage.
====Members====
 
CuviImage methods helps create, copy and show images.
====Methods====
{|class="wikitable"
{|class="wikitable"
|-
|-
! Member name
! Method
! Type
! Description
! Description
|-
|-
| data
| CuviImage()
| void*
| Default constructor. Initializes all members with 0
| Data pointer containing the image pixel values on device
|-
| CuviImage(const Cuvi32s width, const Cuvi32s height, const Cuvi32s depth, const Cuvi32s channels);
| Creates a CuviImage of specified width, height, depth and channels.
|-
| CuviImage(const CuviSize& size, const Cuvi32s depth, const Cuvi32s channels);
| Creates a CuviImage of specified size, depth and channels.
|-
| CuviImage(const CuviImage&);
| Creates a copy of existing CuviImage
|-
| CuviStatus upload(const void* pSrcHost, Cuvi32s srcPitch);
| Copy image data from host memory to CuviImage.
|-
| CuviStatus upload(const void* pSrcHost, Cuvi32s srcPitch, const CuviStream& stream);
| Copy image data asynchronously, from host memory to CuviImage using the specified CuviStream.
|-
| CuviStatus download(void* pDstHost, Cuvi32s dstPitch);
| Copy image data from CuviImage to host memory.
|-
| CuviStatus download(void* pDstHost, Cuvi32s dstPitch, const CuviStream& stream);
| Copy image data asynchronously,from CuviImage to host memory using the specified CuviStream.
|-
| CuviStatus show(const std::string& title = "CUVI Image",Cuvi32s milliseconds = 0);
| Render CuviImage on screen for a specified amount of time
|-
| CuviStatus create(const Cuvi32s width, const Cuvi32s height, const Cuvi32s depth, const Cuvi32s channels);
| Creates a CuviImage of specified width, height, depth and channels. Used for lazy initialization of a previously declared CuviImage.
|-
|-
| width
| CuviStatus create(const CuviSize& size, const Cuvi32s depth, const Cuvi32s channels);
| Cuvi32u
| Creates a CuviImage of specified size, depth and channels. Used for lazy initialization of a previously declared CuviImage.
| Image width in pixels
|-
|-
| height
| CuviStatus release();
| Cuvi32u
| Deallocates a CuviImage object.
| Image height in pixels
|-
|-
| pitch
| ~CuviImage();
| size_t
| CuviImage destructor. Calls release().
| Image pitch/widthstep in bytes
|-
|-
| depth
| Cuvi32s width();
| Cuvi32u
| Returns the width of CuviImage in pixels.
| Defines the data container for the image. A depth of '8' creates CuviImage of type Cuvi8u
|-
|-
| dataBits
| Cuvi32s height();
| Cuvi32u
| Returns the height of CuviImage in pixels.
| No. of bits containing image information. By default dataBits is equal to the depth of the image
|-
|-
| nChannels
| Cuvi32s depth();
| Cuvi32u
| Returns the depth of CuviImage.
| Number of channels in image
|-
|-
| isSigned
| Cuvi32s pitch();
| bool
| Returns the size of a row in bytes, including the padding of the row.
| Specifies if the image also contains negative values. (float is an exception)
 
|-
|-
| isInitialized
| Cuvi32s channels();
| bool
| Returns the number of channels of the CuviImage.
| Specifies if the image has successfully been created on the device
 
|-
|-
| channelSequence
| CuviSize size();
| CuviChannelSeq
| Returns the size of CuviImage.
| Specifies the arrangement of image channels like RGB and BGR
|}
CuviImage methods helps create, copy and show images. All methods return CuviStatus except constructors and destructor which throws an exception in case of failure.
====Methods====
{|class="wikitable"
|-
|-
! Method
| Cuvi32s dataBits();
! Description
| Returns the number of actual data bits of the image.
|-
|-
| CuviImage()
| CuviType type();
| Default constructor. Initializes all members with 0
| Returns the type of CuviImage, e.g. CUVI_8UC1, CUVI_8UC3.
|-
|-
| CuviImage(CuviSize size, Cuvi32u depth, Cuvi32u channels);
| CuviChannelSeq channelSeq();  
| Creates a CuviImage of specified size, depth and channels. Throws exception if memory allocation on device fails.
| Returns the channel sequence of the image, e.g. RGB, BGR etc.
|-
|-
| CuviImage(const CuviImage&);
| bool isSigned();  
| Creates a copy of existing CuviImage
| Returns true in case of unsigned or floating point image type, else returns false.
|-
|-
| CuviImage(const CuviMat&);
| bool isInitialized();  
| Creates a copy of existing CuviMat
| Returns whether the image has been initialized.
|-
|-
| CuviStatus upload(void* pSrcHost, size_t srcPitch, CuviStream* stream = NULL);  
| void* ptr();  
| Copy image data from host memory to CuviImage. This function also supports async operation
| Returns the GPU data pointer of the image.
|-
|-
| CuviStatus download(void* pDstHost, size_t dstPitch, CuviStream* stream = NULL);
| T* ptr<T>();  
| Copy image data from CuviImage to host memory.
| Returns the GPU data pointer as the specified type.
|-
|-
| CuviStatus show(char* title = "CUVI Image",int milliseconds = 0);
| void setDataBits(const Cuvi32s dataBits);  
| Render CuviImage on screen for a specified amount of time
| Set the dataBits of the image.
 
|-
|-
| ~CuviImage();  
| void setChannelSequence(const CuviChannelSeq sequence);  
| CuviImage destructor. Throws an exception in case of failure
| Set the channel sequence of the image.
|}


|}
====I/O using CuviImage====
====I/O using CuviImage====
{|
{|
|style="font-size:125%;"|
|style="font-size:125%;"|
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">


//We start by assuming that user has an image named 'img' allocated on host
#include<iostream>
 
#include<cuvi.h>
//Size of the image
CuviSize size = cuviSize(img->width,img->height);


//Creating two empty CuviImage objects on device to hold input and output images
using namespace std;
CuviImage* gimg = new CuviImage(size,img->depth,img->nChannels);
CuviImage* gout = new CuviImage(size,img->depth,img->nChannels);


//Populate input device image using the host image data
int main()
gimg->upload(img->imageData,img->widthStep);
{
    try
    {
          const char* imagePath = "image.jpg";
          CuviImage input = cuvi::io::loadImage(imagePath);
          if(!input.isInitialized())
          {
            cout<<"Image Not Loaded"<<endl;
            return -1;
          }


//Calling a CUVI function that takes negative of the input image
          CuviImage output;
cuvi::arithmeticLogical::NOT(gimg,gout);


//Shows the result on screen without copying the data to the host
          cuvi::arithmeticLogical::NOT(input,output);
gout->show("Negative");
 
          output.show("Negative Image");


//Copy back the results to an host image named 'output'
          const char* outputPath = "output.jpg";
gout->download(output->imageData,output->widthStep);


//Freeing GPU Memory
          cuvi::io::saveImage(output,outputPath);
delete gimg;
delete gout;


    }
    catch(const char* e)
    {
          cout<<"Error: "<<endl<<e<<endl;
    }
    return 0;
}
</syntaxhighlight>
</syntaxhighlight>
|}
|}
Line 133: Line 151:
**imageStatistics
**imageStatistics
**imageTransforms
**imageTransforms
 
**io
 
**device
==Using CUVI with C==
In C interface structure named CuviMat provides the same functionality as CuviImage. CuviMat offers same members as CuviImage and equivalent methods for initialization and data transfer.
 
====I/O using CuviMat====
 
 
{|
|style="font-size:125%;"|
<syntaxhighlight lang="c">
 
//We start by assuming that user has an image named 'img' allocated on host
 
//declaring variables
CuviSize size;
CuviMat* gimg, *gout;
 
//Size of the image
size = cuviSize(img->width,img->height);
 
//Creating two empty CuviMat objects on device to hold input and output images
cuviCreateMat(&gimg,size,img->depth,img->nChannels);
cuviCreateMat(&gimg,size,img->depth,img->nChannels);
 
//Populate input device image using the host image data
cuviUploadData(gimg,img->imageData,img->widthStep,0);
 
//Calling a CUVI function that takes negative of the input image
cuviNOT(gimg,gout,0);
 
//Shows the result on screen without copying the data to the host
cuviShowMat("Negative",gout,0);
 
//Copy back the results to an host image named 'output'
cuviDownloadData(gout,output->imageData,output->widthStep,0);
 
//Freeing GPU memory
cuviDestroyMat(&gimg);
cuviDestroyMat(&gout);
 
</syntaxhighlight>
|}

Revision as of 16:03, 27 March 2018

Using CUVI with C++

CUVI C++ interface uses various features of C++ including classes, namespaces, default arguments and overloading to provide ease of use.

CuviImage

CuviImage is a C++ class to hold image data on the device. It has all the essential members to hold image information as well as methods to create and move image to and from device. All the C++ functions in CUVI take CuviImage as input/output image argument. CuviImage creates an image on the GPU so you do not need to cater for manually copying the image to the GPU and then back to the CPU, this is catered by CuviImage.

CuviImage methods helps create, copy and show images.

Methods

Method Description
CuviImage() Default constructor. Initializes all members with 0
CuviImage(const Cuvi32s width, const Cuvi32s height, const Cuvi32s depth, const Cuvi32s channels); Creates a CuviImage of specified width, height, depth and channels.
CuviImage(const CuviSize& size, const Cuvi32s depth, const Cuvi32s channels); Creates a CuviImage of specified size, depth and channels.
CuviImage(const CuviImage&); Creates a copy of existing CuviImage
CuviStatus upload(const void* pSrcHost, Cuvi32s srcPitch); Copy image data from host memory to CuviImage.
CuviStatus upload(const void* pSrcHost, Cuvi32s srcPitch, const CuviStream& stream); Copy image data asynchronously, from host memory to CuviImage using the specified CuviStream.
CuviStatus download(void* pDstHost, Cuvi32s dstPitch); Copy image data from CuviImage to host memory.
CuviStatus download(void* pDstHost, Cuvi32s dstPitch, const CuviStream& stream); Copy image data asynchronously,from CuviImage to host memory using the specified CuviStream.
CuviStatus show(const std::string& title = "CUVI Image",Cuvi32s milliseconds = 0); Render CuviImage on screen for a specified amount of time
CuviStatus create(const Cuvi32s width, const Cuvi32s height, const Cuvi32s depth, const Cuvi32s channels); Creates a CuviImage of specified width, height, depth and channels. Used for lazy initialization of a previously declared CuviImage.
CuviStatus create(const CuviSize& size, const Cuvi32s depth, const Cuvi32s channels); Creates a CuviImage of specified size, depth and channels. Used for lazy initialization of a previously declared CuviImage.
CuviStatus release(); Deallocates a CuviImage object.
~CuviImage(); CuviImage destructor. Calls release().
Cuvi32s width(); Returns the width of CuviImage in pixels.
Cuvi32s height(); Returns the height of CuviImage in pixels.
Cuvi32s depth(); Returns the depth of CuviImage.
Cuvi32s pitch(); Returns the size of a row in bytes, including the padding of the row.
Cuvi32s channels(); Returns the number of channels of the CuviImage.
CuviSize size(); Returns the size of CuviImage.
Cuvi32s dataBits(); Returns the number of actual data bits of the image.
CuviType type(); Returns the type of CuviImage, e.g. CUVI_8UC1, CUVI_8UC3.
CuviChannelSeq channelSeq(); Returns the channel sequence of the image, e.g. RGB, BGR etc.
bool isSigned(); Returns true in case of unsigned or floating point image type, else returns false.
bool isInitialized(); Returns whether the image has been initialized.
void* ptr(); Returns the GPU data pointer of the image.
T* ptr<T>(); Returns the GPU data pointer as the specified type.
void setDataBits(const Cuvi32s dataBits); Set the dataBits of the image.
void setChannelSequence(const CuviChannelSeq sequence); Set the channel sequence of the image.

I/O using CuviImage

#include<iostream>
#include<cuvi.h>

using namespace std;

int main()
{
    try
    {
          const char* imagePath = "image.jpg";
          CuviImage input = cuvi::io::loadImage(imagePath);
 
          if(!input.isInitialized())
          {
             cout<<"Image Not Loaded"<<endl;
             return -1;
          }

          CuviImage output;

          cuvi::arithmeticLogical::NOT(input,output);
  
          output.show("Negative Image");

          const char* outputPath = "output.jpg";

          cuvi::io::saveImage(output,outputPath);

    }
    catch(const char* e)
    {
           cout<<"Error: "<<endl<<e<<endl;
    }
    return 0;
}

Namespaces

CUVI is divided in image processing modules based on functionality. These modules use separate namespace in CUVI C++ interface to increase readability and ease of use. The current CUVI version has following namespaces:

  • cuvi
    • arithmeticLogical
    • colorOpertions
    • computerVision
    • dataExchange
    • geometryTransforms
    • imageFiltering
    • imageStatistics
    • imageTransforms
    • io
    • device