Darwin  1.10(beta)
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | List of all members
drwnImageCache Class Reference

Caches images in memory up to a maximum number of images or memory limit. More...

Public Member Functions

 drwnImageCache (bool bGreyImages=GREY_IMAGES, bool bBigMemory=BIG_MEMORY)
 drwnImageCache (const vector< string > &filenames, bool bGreyImages=GREY_IMAGES, bool bBigMemory=BIG_MEMORY)
 constructor with filename initialization
virtual ~drwnImageCache ()
void initialize (const vector< string > &filenames)
 initializes the cache with a list of filenames (cache must be clear)
void append (const string &filename)
 adds a filename to the list of filenames managed by the cache
void clear ()
 Clear all images from the cache (cannot be called if some images are still locked). Does nothing if in big memory mode.
bool empty () const
 returns true if the cache is empty (but may still be initialized with filenames)
size_t size () const
 returns number of images stored in the cache
size_t numLocked () const
 returns number of locked images in the cache
size_t memory () const
 returns memory used by in-memory images
const string & filename (unsigned indx) const
 return the filename for image indx
int index (const string &filename) const
 returns the index for filename (slow)
void lock (unsigned indx)
 lock an image for use (loads if not already in the cache)
void lock (const string &filename)
 lock an image for use (loads if not already in the cache)
const cv::Mat & get (unsigned indx) const
 returns an image (which must first be locked)
const cv::Mat & get (const string &filename) const
 returns an image (which must first be locked)
void unlock (unsigned indx)
 marks an image as free
void unlock (const string &filename)
 marks an image as free
cv::Mat copy (unsigned indx)
 copies an image without locking it (caller must free the image)
cv::Mat copy (const string &filename)
 copies an image without locking it (caller must free the image)

Static Public Attributes

static size_t MAX_IMAGES = 10000
 maximum number of images in memory at any one time
static size_t MAX_MEMORY = 500000000
 maximum number of bytes used at any one time
static bool GREY_IMAGES = false
 default setting for caching images in greyscale
static bool BIG_MEMORY = false
 default setting for big memory mode

Protected Member Functions

void enforceLimits ()
 checks memory and count limits and frees images if exceeded
virtual cv::Mat load (const string &filename) const
 loads an image (can be overrided to perform some pre-processing)

Protected Attributes

vector< string > _filenames
 image filenames
vector< cv::Mat > _images
 loaded images
vector< list< unsigned >
::iterator > 
 ref to location in _free_list
vector< unsigned > _lock_counter
 allows for multiple locks
list< unsigned > _free_list
 index of images that can be safely released in least-recently-used order
bool _bGreyImages
 store images in greyscale (instead of RGB)
bool _bBigMemoryModel
 load all images into memory (ignores MAX_IMAGES and MAX_MEMORY)
size_t _imagesLoaded
 number of images loaded
size_t _memoryUsed
 bytes used by loaded images
unsigned _dbImagesLocked
unsigned _dbImagesLoaded
size_t _dbMaxMemUsed

Detailed Description

Caches images in memory up to a maximum number of images or memory limit.

The cache is initialized with a list of filenames. Images can then be access by index (fast) or by filename (slower). Images must be locked before being used and then unlocked so that the cache can free them if memory limits are exceeded. Images are removed under a least-recently-used (i.e., unlocked) policy. The same image can be locked multiple times. Each lock() must have a corresponding unlock(). The following code shows example usage:

vector<string> filenames = drwnDirectoryListing(directoryName, ".jpg");
drwnImageCache cache(filenames);
while (stillRunning()) {
unsigned int indxA = getFirstImageIndex();
unsigned int indxB = getSecondImageIndex();
const cv::Mat imgA = cache.get(indxA);
const cv::Mat imgB = cache.get(indxB);
processImages(imgA, imgB);

The class can be initialized in big memory mode. In this mode all images are pre-loaded and memory/size limits are ignored, resulting in much faster calls to the lock() and unlock() functions, but may consume all available memory. Big memory mode can be enabled/disabled explicitly via the class constructor. Its default setting is controlled via the BIG_MEMORY static data member.

This class is thread-safe (under Linux).
See Also

The documentation for this class was generated from the following files: