Loading...
Searching...
No Matches
HDF5Image.h
Go to the documentation of this file.
//# HDF5Image.h: astronomical image in HDF5 format
//# Copyright (C) 2008
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef IMAGES_HDF5IMAGE_H
#define IMAGES_HDF5IMAGE_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/images/Images/ImageInterface.h>
#include <casacore/images/Images/ImageAttrHandlerHDF5.h>
#include <casacore/lattices/Lattices/HDF5Lattice.h>
#include <memory>
//# Forward Declarations
#include <casacore/casa/iosfwd.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
// <summary>
// Read, store, and manipulate astronomical images in HDF5 format.
// </summary>
// <use visibility=export>
// <reviewed reviewer="" date="" tests="tHDF5Image.cc" demos="dHDF5Image.cc">
// </reviewed>
// <prerequisite>
// <li> <linkto class=CoordinateSystem>CoordinateSystem</linkto>
// <li> <linkto class=ImageInterface>ImageInterface</linkto>
// <li> <linkto class=Lattice>Lattice</linkto>
// <li> <linkto class=LatticeIterator>LatticeIterator</linkto>
// <li> <linkto class=LatticeNavigator>LatticeNavigator</linkto>
// <li> <linkto class=ImageRegion>ImageRegion</linkto>
// </prerequisite>
// <etymology>
// The HDF5Image name comes from its role as the Image class using HDF5.
// </etymology>
// <synopsis>
// All Casacore 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 <src>imagePixelType</src> 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.
//
// </synopsis>
// <example>
// This example shows how to create a mask for an image, fill it, and
// make it known to the image.
// <srcblock>
// // Open the image (as readonly for the moment).
// HDF5Image<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");
// </srcblock>
// 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:
// <ul>
// <li> Use setDefaultMask to make the other mask the default mask.
// This is advisable when the change should be more or less permanent.
// <li> Open the HDF5Image without using a default mask. Thereafter
// a <linkto class=SubImage>SubImage</linkto> object can be created
// from the HDF5Image and the mask. This is advisable when it the
// mask has to be used only one time.
// </ul>
// </example>
// <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.
// </motivation>
// <note>
// When you make a new HDF5Image, and you are transferring
// information from some other HDF5Image, be aware that you
// must copy, manually, things like miscInfo, imageInfo, units,
// logSink (history) to the new file.
// </note>
template <class T> class HDF5Image: public ImageInterface<T>
{
public:
// Construct a new Image from shape and coordinate information. The image
// will be stored in the named file.
HDF5Image (const TiledShape& mapShape,
const CoordinateSystem& coordinateInfo,
const String& nameOfNewFile);
// Reconstruct an image from a pre-existing file.
// By default the default pixelmask (if available) is used.
explicit HDF5Image (const String& fileName, MaskSpecifier = MaskSpecifier());
// Copy constructor (reference semantics).
HDF5Image (const HDF5Image<T>& other);
~HDF5Image();
// Assignment operator (reference semantics).
HDF5Image<T>& operator= (const HDF5Image<T>& other);
// Make a copy of the object (reference semantics).
virtual ImageInterface<T>* cloneII() const;
// Get the image type (returns name of derived class).
virtual String imageType() const;
// Return the current HDF5 file name. By default this includes the full path.
// The path preceding the file name can be stripped off on request.
virtual String name (Bool stripPath=False) const;
// Function which changes the shape of the ImageExpr.
// Throws an exception as an HDF5Image cannot be resized.
virtual void resize(const TiledShape& newShape);
// Check for symmetry in data members.
virtual Bool ok() const;
// Return the shape of the image.
virtual IPosition shape() const;
// Function which extracts an array from the map.
virtual Bool doGetSlice (Array<T>& buffer, const Slicer& theSlice);
// Function to replace the values in the map with soureBuffer.
virtual void doPutSlice (const Array<T>& sourceBuffer,
const IPosition& where,
const IPosition& stride);
// Get a pointer the default pixelmask object used with this image.
// It returns 0 if no default pixelmask is used.
virtual const LatticeRegion* getRegionPtr() const;
// An HDF5Image is always persistent.
virtual Bool isPersistent() const;
// An HDF5Image is always paged to disk.
virtual Bool isPaged() const;
// Is the HDF5Image writable?
virtual Bool isWritable() const;
// Does the image object use a pixelmask?
virtual Bool hasPixelMask() const;
// Get access to the pixelmask used.
// An exception is thrown if the image does not use a pixelmask.
// <group>
virtual const Lattice<Bool>& pixelMask() const;
virtual Lattice<Bool>& pixelMask();
// </group>
// Set the default pixelmask to the mask with the given name
// (which has to exist in the "masks" group).
// If the image file is writable, the setting is persistent by writing
// the name as a keyword.
// If the given mask name is the empty string,
// the default pixelmask is unset.
virtual void setDefaultMask (const String& maskName);
// Use the mask as specified.
// If a mask was already in use, it is replaced by the new one.
virtual void useMask (MaskSpecifier = MaskSpecifier());
// 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.
// <group>
virtual void apply (T (*function)(T));
virtual void apply (T (*function)(const T& ));
virtual void apply (const Functional<T,T>& function);
// </group>
// Add a lattice to this image.
HDF5Image<T>& operator+= (const Lattice<T>& other);
// Function which sets the units associated with the image
// pixels (i.e. the "brightness" unit). <src>setUnits()</src> returns
// False if it cannot set the unit for some reason (e.g. the underlying
// file is not writable).
virtual Bool setUnits (const Unit& newUnits);
// Flushes the new coordinate system to disk if the file is writable.
virtual Bool setCoordinateInfo (const CoordinateSystem& coords);
// These are the true implementations of the paran operator.
// <note> Not for public use </note>
// <group>
virtual T getAt (const IPosition& where) const;
virtual void putAt (const T& value, const IPosition& where);
// </group>
// Replace the miscinfo in the HDF5Image.
// It can fail if, e.g., the underlying file is not writable.
virtual Bool setMiscInfo (const RecordInterface& newInfo);
// 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 file is not writable.
virtual Bool setImageInfo(const ImageInfo& info);
// Get access to the attribute handler.
// If a handler keyword does not exist yet, it is created if
// <src>createHandler</src> is set.
// Otherwise the handler is empty and no groups can be created for it.
virtual ImageAttrHandler& attrHandler (Bool createHandler=False);
// 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.
// <br>Optionally an exception is thrown if the region does not exist.
virtual void removeRegion (const String& name,
RegionHandler::GroupType = RegionHandler::Any,
Bool throwIfUnknown = True);
// This is the implementation of the letter for the envelope Iterator
// class. <note> Not for public use </note>.
virtual LatticeIterInterface<T>* makeIter
(const LatticeNavigator& navigator,
Bool useRef) const;
// Returns the maximum recommended number of pixels for a cursor. This is
// the number of pixels in a tile.
virtual uInt advisedMaxPixels() const;
// Help the user pick a cursor for most efficient access.
virtual IPosition doNiceCursorShape (uInt maxPixels) const;
// Flush the data.
virtual void flush();
private:
// Function to return the internal HDF5File object to the RegionHandler.
static const std::shared_ptr<HDF5File>& getFile (void* imagePtr);
// This must be called in every constructor and place where the image
// is attached to a new image.
void attach_logtable();
void open_logtable();
void restoreUnits (const RecordInterface& rec);
void restoreMiscInfo (const RecordInterface& rec);
void restoreImageInfo (const RecordInterface& rec);
void restoreAll();
void check_conformance (const Lattice<T>& other);
void applyMaskSpecifier (const MaskSpecifier&);
void applyMask (const String& maskName);
//# Data members.
HDF5Lattice<T> map_p;
LatticeRegion* regionPtr_p;
ImageAttrHandlerHDF5 itsAttrHandler;
//# Make members of parent class known.
public:
using ImageInterface<T>::logSink;
using ImageInterface<T>::logger;
using ImageInterface<T>::imageInfo;
using ImageInterface<T>::coordinates;
using ImageInterface<T>::getDefaultMask;
using ImageInterface<T>::hasRegion;
using ImageInterface<T>::getImageRegionPtr;
protected:
using ImageInterface<T>::setCoordsMember;
using ImageInterface<T>::setMiscInfoMember;
using ImageInterface<T>::setLogMember;
using ImageInterface<T>::setUnitMember;
using ImageInterface<T>::setImageInfoMember;
};
// Tell if HDF5 images can be used.
inline Bool canUseHDF5Image()
{ return HDF5Object::hasHDF5Support(); }
// Determine the pixel type in the HDF5Image contained in
// <src>fileName</src>. If the file doesn't appear to be HDF5 or cannot
// be opened, TpOther is returned.
// <group name="pixeltype")
DataType hdf5imagePixelType (const String& fileName);
// Check if this HDF5 file is an HDF5 image.
Bool isHDF5Image (const String& fileName);
// </group>
} //# NAMESPACE CASACORE - END
#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/images/Images/HDF5Image.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif
casacore::Array
Definition Array.h:155
casacore::CoordinateSystem
Definition CoordinateSystem.h:215
casacore::Functional
Definition Functional.h:120
casacore::HDF5Image::name
virtual String name(Bool stripPath=False) const
Return the current HDF5 file name.
casacore::HDF5Image::getAt
virtual T getAt(const IPosition &where) const
These are the true implementations of the paran operator.
casacore::HDF5Image::HDF5Image
HDF5Image(const TiledShape &mapShape, const CoordinateSystem &coordinateInfo, const String &nameOfNewFile)
Construct a new Image from shape and coordinate information.
casacore::HDF5Image::restoreImageInfo
void restoreImageInfo(const RecordInterface &rec)
casacore::HDF5Image::applyMask
void applyMask(const String &maskName)
casacore::HDF5Image::isWritable
virtual Bool isWritable() const
Is the HDF5Image writable?
casacore::HDF5Image::operator+=
HDF5Image< T > & operator+=(const Lattice< T > &other)
Add a lattice to this image.
casacore::HDF5Image::HDF5Image
HDF5Image(const HDF5Image< T > &other)
Copy constructor (reference semantics).
casacore::HDF5Image::setUnits
virtual Bool setUnits(const Unit &newUnits)
Function which sets the units associated with the image pixels (i.e.
casacore::HDF5Image::putAt
virtual void putAt(const T &value, const IPosition &where)
Put the value of a single element.
casacore::HDF5Image::doPutSlice
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Function to replace the values in the map with soureBuffer.
casacore::HDF5Image::doNiceCursorShape
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Help the user pick a cursor for most efficient access.
casacore::HDF5Image::~HDF5Image
~HDF5Image()
casacore::HDF5Image::regionPtr_p
LatticeRegion * regionPtr_p
Definition HDF5Image.h:301
casacore::HDF5Image::setMiscInfo
virtual Bool setMiscInfo(const RecordInterface &newInfo)
Replace the miscinfo in the HDF5Image.
casacore::HDF5Image::doGetSlice
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &theSlice)
Function which extracts an array from the map.
casacore::HDF5Image::shape
virtual IPosition shape() const
Return the shape of the image.
casacore::HDF5Image::apply
virtual void apply(T(*function)(T))
Replace every element, x, of the lattice with the result of f(x).
casacore::HDF5Image::flush
virtual void flush()
Flush the data.
casacore::HDF5Image::imageType
virtual String imageType() const
Get the image type (returns name of derived class).
casacore::HDF5Image::setImageInfo
virtual Bool setImageInfo(const ImageInfo &info)
The ImageInfo object contains some miscellaneous information about the image, which unlike that store...
casacore::HDF5Image::attrHandler
virtual ImageAttrHandler & attrHandler(Bool createHandler=False)
Get access to the attribute handler.
casacore::HDF5Image::HDF5Image
HDF5Image(const String &fileName, MaskSpecifier=MaskSpecifier())
Reconstruct an image from a pre-existing file.
casacore::HDF5Image::open_logtable
void open_logtable()
casacore::HDF5Image::isPersistent
virtual Bool isPersistent() const
An HDF5Image is always persistent.
casacore::HDF5Image::apply
virtual void apply(T(*function)(const T &))
casacore::HDF5Image::applyMaskSpecifier
void applyMaskSpecifier(const MaskSpecifier &)
casacore::HDF5Image::map_p
HDF5Lattice< T > map_p
Definition HDF5Image.h:300
casacore::HDF5Image::cloneII
virtual ImageInterface< T > * cloneII() const
Make a copy of the object (reference semantics).
casacore::HDF5Image::pixelMask
virtual Lattice< Bool > & pixelMask()
casacore::HDF5Image::ok
virtual Bool ok() const
Check for symmetry in data members.
casacore::HDF5Image::setCoordinateInfo
virtual Bool setCoordinateInfo(const CoordinateSystem &coords)
Flushes the new coordinate system to disk if the file is writable.
casacore::HDF5Image::removeRegion
virtual void removeRegion(const String &name, RegionHandler::GroupType=RegionHandler::Any, Bool throwIfUnknown=True)
Remove a region/mask belonging to the image from the given group (which can be Any).
casacore::HDF5Image::restoreUnits
void restoreUnits(const RecordInterface &rec)
casacore::HDF5Image::operator=
HDF5Image< T > & operator=(const HDF5Image< T > &other)
Assignment operator (reference semantics).
casacore::HDF5Image::advisedMaxPixels
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
casacore::HDF5Image::resize
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the ImageExpr.
casacore::HDF5Image::restoreMiscInfo
void restoreMiscInfo(const RecordInterface &rec)
casacore::HDF5Image::getRegionPtr
virtual const LatticeRegion * getRegionPtr() const
Get a pointer the default pixelmask object used with this image.
casacore::HDF5Image::setDefaultMask
virtual void setDefaultMask(const String &maskName)
Set the default pixelmask to the mask with the given name (which has to exist in the "masks" group).
casacore::HDF5Image::attach_logtable
void attach_logtable()
This must be called in every constructor and place where the image is attached to a new image.
casacore::HDF5Image::useMask
virtual void useMask(MaskSpecifier=MaskSpecifier())
Use the mask as specified.
casacore::HDF5Image::check_conformance
void check_conformance(const Lattice< T > &other)
casacore::HDF5Image::restoreAll
void restoreAll()
casacore::HDF5Image::makeIter
virtual LatticeIterInterface< T > * makeIter(const LatticeNavigator &navigator, Bool useRef) const
This is the implementation of the letter for the envelope Iterator class; Note: Not for public use ...
casacore::HDF5Image::apply
virtual void apply(const Functional< T, T > &function)
casacore::HDF5Image::hasPixelMask
virtual Bool hasPixelMask() const
Does the image object use a pixelmask?
casacore::HDF5Image::isPaged
virtual Bool isPaged() const
An HDF5Image is always paged to disk.
casacore::HDF5Image::getFile
static const std::shared_ptr< HDF5File > & getFile(void *imagePtr)
Function to return the internal HDF5File object to the RegionHandler.
casacore::HDF5Image::itsAttrHandler
ImageAttrHandlerHDF5 itsAttrHandler
Definition HDF5Image.h:302
casacore::HDF5Image::pixelMask
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask used.
casacore::HDF5Lattice
Definition HDF5Lattice.h:108
casacore::HDF5Object::hasHDF5Support
static Bool hasHDF5Support()
Check if there is HDF5 support compiled in.
casacore::IPosition
Definition IPosition.h:117
casacore::ImageAttrHandlerHDF5
Definition ImageAttrHandlerHDF5.h:87
casacore::ImageAttrHandler
Definition ImageAttrHandler.h:90
casacore::ImageInfo
Definition ImageInfo.h:90
casacore::ImageInterface::logSink
LogIO & logSink()
Allow messages to be logged to this ImageInterface.
Definition ImageInterface.h:210
casacore::ImageInterface::setCoordsMember
void setCoordsMember(const CoordinateSystem &coords)
Set the coordinate system variable.
Definition ImageInterface.h:365
casacore::ImageInterface::logger
LoggerHolder & logger()
Get access to the LoggerHolder.
Definition ImageInterface.h:202
casacore::ImageInterface::setLogMember
void setLogMember(const LoggerHolder &logger)
Set the image logger variable.
Definition ImageInterface.h:358
casacore::ImageInterface::imageInfo
const ImageInfo & imageInfo() const
The ImageInfo object contains some miscellaneous information about the image which unlike that stored...
Definition ImageInterface.h:238
casacore::ImageInterface::getDefaultMask
virtual String getDefaultMask() const
Get the name of the default pixelmask.
casacore::ImageInterface::getImageRegionPtr
virtual ImageRegion * getImageRegionPtr(const String &name, RegionHandler::GroupType=RegionHandler::Any, Bool throwIfUnknown=True) const
Get a region/mask belonging to the image from the given group (which can be Any).
casacore::ImageInterface::ImageInterface
ImageInterface()
casacore::ImageInterface::setImageInfoMember
void setImageInfoMember(const ImageInfo &imageInfo)
Set the image info variable.
casacore::ImageInterface::hasRegion
virtual Bool hasRegion(const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
Does the image have a region with the given name?
casacore::ImageInterface::setMiscInfoMember
void setMiscInfoMember(const RecordInterface &rec)
Set the miscinfo variable.
Definition ImageInterface.h:373
casacore::ImageInterface::coordinates
const CoordinateSystem & coordinates() const
Definition ImageInterface.h:193
casacore::ImageInterface::setUnitMember
void setUnitMember(const Unit &unit)
Set the unit variable.
Definition ImageInterface.h:369
casacore::LatticeIterInterface
Definition LatticeIterInterface.h:112
casacore::LatticeNavigator
Definition LatticeNavigator.h:180
casacore::LatticeRegion
Definition LatticeRegion.h:72
casacore::Lattice
Definition Lattice.h:230
casacore::MaskSpecifier
Definition MaskSpecifier.h:68
casacore::RegionHandler::GroupType
GroupType
Define the possible group types (regions or masks).
Definition RegionHandler.h:97
casacore::RegionHandler::Any
@ Any
Definition RegionHandler.h:100
casacore::Slicer
Definition Slicer.h:287
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore::TiledShape
Definition TiledShape.h:95
casacore::Unit
Definition Unit.h:187
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::False
const Bool False
Definition aipstype.h:42
casacore::isHDF5Image
Bool isHDF5Image(const String &fileName)
Check if this HDF5 file is an HDF5 image.
casacore::uInt
unsigned int uInt
Definition aipstype.h:49
casacore::hdf5imagePixelType
DataType hdf5imagePixelType(const String &fileName)
Determine the pixel type in the HDF5Image contained in fileName.
casacore::RecordInterface
RecordInterface()
The default constructor creates an empty record with a variable structure.
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::canUseHDF5Image
Bool canUseHDF5Image()
Tell if HDF5 images can be used.
Definition HDF5Image.h:323
casacore::True
const Bool True
Definition aipstype.h:41
casacore::value
NewDelAllocator< T > NewDelAllocator< T >::value
Definition Allocator.h:368