PagedImage.h
Classes
- PagedImage -- Read, store, and manipulate astronomical images. (full description)
Interface
- Public Members
- PagedImage (const TiledShape& mapShape, const CoordinateSystem& coordinateInfo, Table& table, uInt rowNumber = 0)
- PagedImage (const TiledShape& mapShape, const CoordinateSystem& coordinateInfo, const String& nameOfNewFile, uInt rowNumber = 0)
- PagedImage (const TiledShape& mapShape, const CoordinateSystem& coordinateInfo, const String& nameOfNewFile, TableLock::LockOption, uInt rowNumber = 0)
- PagedImage (const TiledShape& mapShape, const CoordinateSystem& coordinateInfo, const String& nameOfNewFile, const TableLock& lockOptions, uInt rowNumber = 0)
- explicit PagedImage (Table& table, MaskSpecifier = MaskSpecifier(), uInt rowNumber = 0)
- explicit PagedImage (const String& filename, MaskSpecifier = MaskSpecifier(), uInt rowNumber = 0)
- PagedImage (const String& filename, TableLock::LockOption, MaskSpecifier = MaskSpecifier(), uInt rowNumber = 0)
- PagedImage (const String& filename, const TableLock& lockOptions, MaskSpecifier = MaskSpecifier(), uInt rowNumber = 0)
- PagedImage (const PagedImage<T>& other)
- ~PagedImage()
- PagedImage<T>& operator= (const PagedImage<T>& other)
- virtual ImageInterface<T>* cloneII() const
- virtual String imageType() const
- virtual Bool isPersistent() const
- virtual Bool isPaged() const
- virtual Bool isWritable() const
- virtual Bool hasPixelMask() const
- virtual const Lattice<Bool>& pixelMask() const
- virtual Lattice<Bool>& pixelMask()
- virtual const LatticeRegion* getRegionPtr() const
- virtual void setDefaultMask (const String& maskName)
- virtual void useMask (MaskSpecifier = MaskSpecifier())
- void rename (const String& newName)
- virtual String name (Bool stripPath=False) const
- uInt rowNumber() const
- virtual IPosition shape() const
- virtual void resize (const TiledShape& newShape)
- virtual Bool doGetSlice (Array<T>& buffer, const Slicer& theSlice)
- virtual void doPutSlice (const Array<T>& sourceBuffer, const IPosition& where, const IPosition& stride)
- virtual void apply (T (*function)(T))
- virtual void apply (T (*function)(const T& ))
- virtual void apply (const Functional<T,T>& function)
- PagedImage<T>& operator+= (const Lattice<T>& other)
- virtual Bool setUnits (const Unit& newUnits)
- Table& table()
- virtual Bool setCoordinateInfo (const CoordinateSystem& coords)
- virtual Bool ok() const
- virtual T getAt (const IPosition& where) const
- virtual void putAt (const T& value, const IPosition& where)
- virtual Bool setMiscInfo (const RecordInterface& newInfo)
- virtual Bool setImageInfo(const ImageInfo& info)
- virtual void removeRegion (const String& name, RegionHandler::GroupType = RegionHandler::Any, Bool throwIfUnknown = True)
- virtual LatticeIterInterface<T>* makeIter (const T& navigator, Bool useRef) const
- virtual uInt advisedMaxPixels() const
- virtual IPosition doNiceCursorShape (uInt maxPixels) const
- virtual uInt maximumCacheSize() const
- virtual void setMaximumCacheSize (uInt howManyPixels)
- virtual void setCacheSizeFromPath (const IPosition& sliceShape, const IPosition& windowStart, const IPosition& windowLength, const IPosition& axisPath)
- virtual void setCacheSizeInTiles (uInt howManyTiles)
- virtual void clearCache()
- virtual void showCacheStatistics (ostream& os) const
- virtual Bool lock (FileLocker::LockType, uInt nattempts)
- virtual void unlock()
- virtual Bool hasLock (FileLocker::LockType) const
- virtual void resync()
- virtual void flush()
- virtual void tempClose()
- virtual void reopen()
- Private Members
- static Table& getTable (void* imagePtr, Bool writable)
- void attach_logtable()
- void open_logtable()
- void restoreUnits (const TableRecord& rec)
- void restoreMiscInfo (const TableRecord& rec)
- void restoreImageInfo (const TableRecord& rec)
- void restoreAll (const TableRecord& rec)
- void check_conformance (const Lattice<T>& other)
- void reopenRW()
- void doReopenRW()
- void setTableType()
- void applyMaskSpecifier (const MaskSpecifier&)
- void applyMask (const String& maskName)
- void makePagedImage (const TiledShape& mapShape, const CoordinateSystem& coordinateInfo, const String& nameOfNewFile, const TableLock& lockOptions, uInt rowNumber)
- void makePagedImage (const String& filename, const TableLock& lockOptions, const MaskSpecifier&, uInt rowNumber)
- const Table& table() const
- See Also
- Global functions for PagedImage.
Review Status
- Programs:
- Demos:
- Tests:
Prerequisite
Etymology
The PagedImage name comes from its role as the Image class with paging
from persistent memory. Users are thus invited to treat the
PagedImage instances like AIPS++ Lattices
Synopsis
All AIPS++ Images are Lattices. They may be treated like any other Lattice;
getSlice(...), putSlice(...), LatticeIterator for iterating, etc...
ArrayImages contain a map, a mask for that map, and coordinate
information. This provides a Lattice interface for images and their
respective coordinates. Additional functionality is defined by the
ImageInterface class.
You can use the global function imagePixelType to determine
what the pixel type of an image is before you open the image if your
code can work with Images of many possible types, or for error checking.
Example
This example shows how to create a mask for an image, fill it, and
make it known to the image.
// Open the image (as readonly for the moment).
PagedImage<Float> myimage ("image.name");
// Create a mask for the image.
// The mask will be stored in a subtable of the image.
LCPagedMask mask (RegionHandler::makeMask (myimage, "mask.name"));
// Fill the mask with whatever values (e.g. all True).
mask.set (True);
// Make the mask known to the image (with name mask1).
myimage.defineRegion ("mask1", mask, RegionHandler::Masks);
// Make the mask the default mask for this image.
myimage.setDefaultMask ("mask1");
It is possible to create as many masks as one likes. They can all
be defined as masks for the image (with different names, of course).
However, only one of them can be the default mask (the mask used
by default when the image is opened). When another mask has to be
used, one can do two things:
- Use setDefaultMask to make the other mask the default mask.
This is advisable when the change should be more or less permanent.
- Open the PagedImage without using a default mask. Thereafter
a SubImage object can be created
from the PagedImage and the mask. This is advisable when it the
mask has to be used only one time.
Motivation
The size of astronomical data can be very large. The ability to fit an
entire image into random access memory cannot be guaranteed. Paging from
disk pieces of the image appeared to be the way to deal with this problem.
When you make a new PagedImage, and you are transferring
information from some other PagedImage, be aware that you
must copy, manually, things like miscInfo, imageInfo, units,
logSink (history) to the new file.
To Do
- The CoordinateSystem::store() function returns a TableRecord. That
TableRecord should be stored in the same row as our image. This will
allow ImageStack members to have their own coordinate frames.
Member Description
Construct a new Image from shape and coordinate information.
Data will be stored in the argument table.
PagedImage (const TiledShape& mapShape, const CoordinateSystem& coordinateInfo, const String& nameOfNewFile, uInt rowNumber = 0)
Construct a new Image from shape and coordinate information. Table
will be stored in the named file.
PagedImage (const TiledShape& mapShape, const CoordinateSystem& coordinateInfo, const String& nameOfNewFile, TableLock::LockOption, uInt rowNumber = 0)
PagedImage (const TiledShape& mapShape, const CoordinateSystem& coordinateInfo, const String& nameOfNewFile, const TableLock& lockOptions, uInt rowNumber = 0)
Construct a new Image from shape and coordinate information. Table
will be stored in the named file.
The lock options may be specified
explicit PagedImage (Table& table, MaskSpecifier = MaskSpecifier(), uInt rowNumber = 0)
Reconstruct an image from a pre-existing file.
By default the default pixelmask (if available) is used.
explicit PagedImage (const String& filename, MaskSpecifier = MaskSpecifier(), uInt rowNumber = 0)
Reconstruct an image from a pre-existing file.
By default the default pixelmask (if available) is used.
PagedImage (const String& filename, TableLock::LockOption, MaskSpecifier = MaskSpecifier(), uInt rowNumber = 0)
PagedImage (const String& filename, const TableLock& lockOptions, MaskSpecifier = MaskSpecifier(), uInt rowNumber = 0)
Reconstruct an image from a pre-existing file with Locking.
By default the default pixelmask (if available) is used.
PagedImage (const PagedImage<T>& other)
Copy constructor (reference semantics).
PagedImage<T>& operator= (const PagedImage<T>& other)
Assignment operator (reference semantics).
virtual ImageInterface<T>* cloneII() const
Make a copy of the object (reference semantics).
Get the image type (returns name of derived class).
A PagedImage is always persistent.
virtual Bool isPaged() const
A PagedImage is always paged to disk.
virtual Bool isWritable() const
Is the PagedImage writable?
Does the image object use a pixelmask?
Get access to the pixelmask used.
An exception is thrown if the image does not use a pixelmask.
Get a pointer the default pixelmask object used with this image.
It returns 0 if no default pixelmask is used.
Set the default pixelmask to the mask with the given name
(which has to exist in the "masks" group).
If the image table is writable, the setting is persistent by writing
the name as a keyword.
If the given regionName is the empty string,
the default pixelmask is unset.
Use the mask as specified.
If a mask was already in use, it is replaced by the new one.
Function to change the name of the Table file on disk.
PagedImage is given a file name at construction time. You may change
that name here.
virtual String name (Bool stripPath=False) const
Return the current Table name. By default this includes the full path.
the path preceding the file name can be stripped off on request.
Return the current TableColumn row number.
Return the shape of the image.
Change the shape of the image (N.B. the data is thrown away).
virtual Bool doGetSlice (Array<T>& buffer, const Slicer& theSlice)
Function which extracts an array from the map.
virtual void doPutSlice (const Array<T>& sourceBuffer, const IPosition& where, const IPosition& stride)
Function to replace the values in the map with soureBuffer.
virtual void apply (T (*function)(T))
virtual void apply (T (*function)(const T& ))
virtual void apply (const Functional<T,T>& function)
Replace every element, x, of the lattice with the result of f(x).
you must pass in the address of the function -- so the function
must be declared and defined in the scope of your program.
Both versions of apply require a function that accepts a single
argument of type T (the Lattice template actual type) and returns
a result of the same type. The first apply expects a function with
an argument passed by value; the second expects the argument to
be passed by const reference. The first form ought to run faster
for the built-in types, which may be an issue for large Lattices
stored in memory, where disk access is not an issue.
PagedImage<T>& operator+= (const Lattice<T>& other)
Add a lattice to this image.
virtual Bool setUnits (const Unit& newUnits)
Function which sets the units associated with the image
pixels (i.e. the "brightness" unit). setUnits() returns
False if it cannot set the unit for some reason (e.g. the underlying
file is not writable).
Return the table holding the data.
Flushes the new coordinate system to disk if the table is writable.
virtual Bool ok() const
Check for symmetry in data members.
virtual T getAt (const IPosition& where) const
virtual void putAt (const T& value, const IPosition& where)
These are the true implementations of the paran operator.
Not for public use
virtual Bool setMiscInfo (const RecordInterface& newInfo)
Replace the miscinfo in the PagedImage.
It can fail if, e.g., the underlying table is not writable.
The ImageInfo object contains some miscellaneous information about the
image, which unlike that stored in MiscInfo, has a standard list of
things, such as the restoring beam.
Note that setImageInfo REPLACES the information with the new information.
It can fail if, e.g., the underlying table is not writable.
Remove a region/mask belonging to the image from the given group
(which can be Any).
If a mask removed is the default mask, the image gets unmasked.
Optionally an exception is thrown if the region does not exist.
virtual LatticeIterInterface<T>* makeIter (const T& navigator, Bool useRef) const
This is the implementation of the letter for the envelope Iterator
class. Not for public use .
Returns the maximum recommended number of pixels for a cursor. This is
the number of pixels in a tile.
Help the user pick a cursor for most efficient access.
Maximum size - not necessarily all used. In pixels.
Set the maximum (allowed) cache size as indicated.
Set the cache size as to "fit" the indicated path.
Set the actual cache size for this Array to be be big enough for the
indicated number of tiles. This cache is not shared with PagedArrays
in other rows and is always clipped to be less than the maximum value
set using the setMaximumCacheSize member function.
tiles. Tiles are cached using a first in first out algorithm.
Clears and frees up the caches, but the maximum allowed cache size is
unchanged from when setCacheSize was called
Report on cache success.
virtual Bool lock (FileLocker::LockType, uInt nattempts)
virtual void unlock()
virtual Bool hasLock (FileLocker::LockType) const
Handle the (un)locking.
Unlocking also unlocks the logtable and a possible mask table.
Locking only locks the image itself.
virtual void resync()
Resynchronize the PagedImage object with the table contents.
The logtable and possible mask table are also synchronized if
they do not have a readlock.
This function is only useful if no read-locking is used, ie.
if the table lock option is UserNoReadLocking or AutoNoReadLocking.
In that cases the table system does not acquire a read-lock, thus
does not synchronize itself automatically.
virtual void flush()
Flush the data.
Close the Image and associated files temporarily.
It'll be reopened automatically when needed or when
reopen is called explicitly.
virtual void reopen()
If needed, reopen a temporarily closed Image..
static Table& getTable (void* imagePtr, Bool writable)
Function to return the internal Table object to the RegionHandler.
This must be called in every constructor and place where the image
is attached to a new image.