Loading...
Searching...
No Matches
WCBox.h
Go to the documentation of this file.
//# WCBox.h: Class to define a box shaped WC region
//# Copyright (C) 1998,1999,2001
//# 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_WCBOX_H
#define IMAGES_WCBOX_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/coordinates/Coordinates/CoordinateSystem.h>
#include <casacore/images/Regions/WCRegion.h>
#include <casacore/lattices/LRegions/RegionType.h>
#include <casacore/casa/Arrays/Vector.h>
#include <casacore/casa/Quanta/Quantum.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward Declarations
class LCRegion;
class TableRecord;
class IPosition;
// <summary>
// Class to define a world coordinate box region of interest in an image.
// </summary>
//
// <use visibility=export>
//
// <reviewed reviewer="" date="" tests="">
// </reviewed>
//
// <prerequisite>
// <li> <linkto class=WCRegion>WCRegion</linkto>
// <li> <linkto class=LCRegion>LCRegion</linkto>
// <li> <linkto class=CoordinateSystem>CoordinateSystem</linkto>
// </prerequisite>
//
// <synopsis>
// The corners of the box are specified in world coordinates, but the
// region enclosed by those corners is a box in lattice coordinates.
// Thus, the volume enclosed does not follow world coordinate contours.
//
// All this class does, apart from constructing itself, is know
// how to save itself to a <src>Record</src> and how to convert itself
// to an <src>LCRegion</src>. The conversion allows you to apply
// a <src>WCBox</src> constructed with one <src>CoordinateSystem</src>
// to another <src>CoordinateSystem</src>. That is, you can apply a
// <src>WCBox</src> from this image to that image.
//
// The flexibility of the <src>CoordinateSystem</src> class should
// be kept in mind when using this class. Recall that a
// <src>CoordinateSystem</src> has world and pixel axes, and
// that these axes can be independently removed and independently
// (re)ordered.
//
// During construction, the length of the world coordinate vectors may be
// smaller than the number world axes in the supplied <src>CoordinateSystem</src>.
// It is assumed that the units of the world coordinates are the same as those
// encapsulated in the construction <src>CoordinateSystem</src> and in the same
// order as specified (either intrinsically, or by the world axes
// specification vectors).
//
// The following rules are followed during conversion to an <src>LCRegion</src>.
// <ol>
// <li> The number of elements in the supplied <src>latticeShape</src> must be equal
// to the number of pixel axes in the supplied <src>CoordinateSystem</src>.
// <li> The order of the pixel axes in the supplied <src>CoordinateSystem</src>
// is assumed to be the order of the axes in the lattice for which the
// supplied <src>latticeShape</src> is appropriate.
// <li> The <src>CoordinateSystem</src> supplied to the <src>toLCRegion</src>
// function does not have to be identical in structure to that from
// which the <src>WCBox</src> was constructed. They can consist
// of different numbers of world and pixel axes and be in different
// orders.
// <li> For every world axis in the supplied <src>CoordinateSystem</src>
// that is also present (somewhere) in the construction <src>CoordinateSystem</src>
// the blc/trc corresponding to that world axis will be
// converted to pixels appropriate to the supplied <src>CoordinateSystem</src>.
// The order of this pixel based blc/trc will be the order of the pixel axes of
// the supplied <src>CoordinateSystem</src>
// <li> For every world axis in the supplied <src>CoordinateSystem</src>
// that is not present in the construction <src>CoordinateSystem</src>,
// the supplied <src>latticeShape</src> value for the corresponding
// pixel axis is used, setting <src>blc=0</src> and <src>trc=latticeShape-1</src>
// for that axis.
// <li> Once the pixel based blc/trc has been created, then, with
// the supplied <src>latticeShape</src>, it is used to create the
// <src>LCBox</src>, which is supplied as a pointer to the base
// class <src>LCRegion</src>.
// </ol>
//
// Note that when determining whether a world axis from one
// <src>CoordinateSystem</src>is present on another, it is
// considered to not be a match if two coordinates of the
// same type (e.g. <src>DirectionCoordinate</src>) have different
// specific types (e.g. J2000 and GALACTIC, or TOPO and LSR for
// a <src>SpectralCoordinate</src>)
// </synopsis>
//
// <example>
// Let us give some examples with pseudo-code.
// cSys is the construction CoordinateSystem
// and cSys2 is the supplied CoordinateSystem.
// We list their world axes in the square brackets.
// The construction blc/trc values don't matter
// as long as there cSys.nWorldAxes() of them.
// Similarly, the values of shape don't matter
// as long as there are cSys2.nPixelAxes() of them.
// <srcblock>
// cSys = [ra, dec, freq];
// cSys2 = [ra, dec];
// blc = [,,];
// trc = [,,];
// shape = [,];
// WCBox box(blc, trc, cSys);
// LCRegion* pR = box.toLCRegion(cSys2, shape);
// </srcblock>
// The resultant LCBox will have corners converted
// according to
// <srcblock>
// blcLC(0) <- blc(0);
// blcLC(1) <- blc(1);
// trcLC(0) <- trc(0);
// trcLC(1) <- trc(1);
// </srcblock>
//
// </example>
//
// <example>
// <srcblock>
// cSys = [ra, dec, freq];
// cSys2 = [freq, stokes];
// blc = [,,];
// trc = [,,];
// shape = [,];
// WCBox box(blc, trc, cSys);
// LCRegion* pR = box.toLCRegion(cSys2, shape);
// </srcblock>
//
// The resultant LCBox will have corners converted
// according to
//
// <srcblock>
// blcLC(0) <- blc(2);
// blcLC(1) = 0;
// trcLC(0) <- trc(2);
// trcLC(1) = shape(1) - 1;
// </srcblock>
//
// </example>
//
// <example>
// <srcblock>
// cSys = [ra, dec];
// cSys2 = [ra, dec, freq];
// blc = [,];
// trc = [,];
// shape = [,,];
// WCBox box(blc, trc, cSys);
// LCRegion* pR = box.toLCRegion(cSys2, shape);
// </srcblock>
//
// The resultant LCBox will have corners converted
// according to
//
// <srcblock>
// blcLC(0) <- blc(0);
// blcLC(1) <- blc(1);
// blcLC(2) = 0l
// trcLC(0) <- trc(0);
// trcLC(1) <- trc(1);
// trcLC(2) = shape(2)-1;
// </srcblock>
//
// </example>
//
// <example>
// <srcblock>
// cSys = [ra, dec, freq];
// cSys2 = [freq, ra, dec];
// blc = [,,];
// trc = [,,];
// shape = [,,];
// WCBox box(blc, trc, cSys);
// LCRegion* pR = box.toLCRegion(cSys2, shape);
// </srcblock>
//
// The resultant LCBox will have corners converted
// according to
//
// <srcblock>
// blcLC(0) <- blc(2);
// blcLC(1) <- blc(0);
// blcLC(2) <- blc(1);
// trcLC(0) <- trc(2);
// trcLC(1) <- trc(0);
// trcLC(2) <- trc(1);
// </srcblock>
//
// </example>
//
// <example>
// In this example we make it a bit harder by
// reordering the pixel axes too. The new order
// of the pixel axes in terms of the original
// order [0,1,2] is given after the world axes
//
// <srcblock>
// cSys = [ra, dec, freq], [0, 1, 2];
// cSys2 = [freq, ra, dec, stokes], [3, 0, 2, 1];
// blc = [,,];
// trc = [,,];
// shape = [,,,];
// WCBox box(blc, trc, cSys);
// LCRegion* pR = box.toLCRegion(cSys2, shape);
// </srcblock>
//
// Take the first world axis of cSys2 as an example.
// First, "freq" is found as the world axis number
// 2 in cSys. Then, when it is converted to
// a pixel coordinate, it will turn up as
// the value on pixel axis 1. The supplied shape
// must be appropriate to a [stokes, freq, dec, ra] lattice.
// The resultant LCBox will therefore have corners
// converted according to
//
// <srcblock>
// blcLC(0) = 0
// blcLC(1) <- blc(2);
// blcLC(2) <- blc(1);
// blcLC(3) <- blc(0);
//
// trcLC(0) = shape(0)-1;
// trcLC(1) <- trc(2);
// trcLC(2) <- trc(1);
// trcLC(3) <- trc(0);
// </srcblock>
// </example>
//
// <motivation>
// Users must be able to specify regions in world as well as lattice
// coordinates.
// </motivation>
//
// <note>
// In all of the constructors, the order of the specified world
// coordinates is that of the *PIXEL AXES* (not world axes) in the
// <src>CoordinateSystem</src>. This is the natural order for a user to want
// to specify them in.
// </note>
//
// <note>
// For the constructors specifying the world values as simple doubles,
// it is *ASSUMED* that the units of those doubles are the same as
// the native units of the <src>CoordinateSystem</src> for each axis.
// </note>
//
// <note>
// World coordinates may be specified as absolute or offset. If the
// latter, they are offset with respect to the reference pixel of
// the <src>CoordinateSystem</src>.
// </note>
// <todo asof="1998/05/20">
// <li> Implement offset coordinates
// </todo>
class WCBox : public WCRegion
{
public:
WCBox();
// Construct from vectors of world coordinates
// defining the box corners. It is assumed that the
// order of the values is in the order of the pixel axes
// in the given coordinate system.
// <group>
WCBox(const Vector<Quantum<Double> >& blc,
const Vector<Quantum<Double> >& trc,
const CoordinateSystem& cSys,
const Vector<Int>& absRel);
// </group>
// Construct from vectors of world coordinates
// defining the box corners. You specify the pixel
// axis order of the world values.
// <group>
WCBox(const Vector<Quantum<Double> >& blc,
const Vector<Quantum<Double> >& trc,
const IPosition& pixelAxes,
const CoordinateSystem& cSys,
const Vector<Int>& absRel);
// </group>
// Construct from the bounding box of an <src>LCRegion</src>.
WCBox(const LCRegion& region,
const CoordinateSystem& cSys);
// Copy constructor (reference semantics [except for <src>CoordinateSystem</src>])
WCBox (const WCBox& other);
// Destructor
virtual ~WCBox();
// Assignment (copy semantics)
WCBox& operator= (const WCBox& other);
// Comparison
virtual Bool operator==(const WCRegion& other) const;
// Clone a WCBox object.
virtual WCRegion* cloneRegion() const;
// WCBox can extend a region.
virtual Bool canExtend() const;
// Make a new box from the given axesin this box.
WCBox splitBox (const IPosition& axes) const;
// Convert to an LCRegion using the supplied <src>CoordinateSystem</src>
// and shape.
virtual LCRegion* doToLCRegion (const CoordinateSystem& cSys,
const IPosition& latticeShape,
const IPosition& pixelAxesMap,
const IPosition& outOrder) const;
// Convert the WCBox object to a record.
// The record can be used to make the object persistent.
// The <src>tableName</src> argument can be used by derived
// classes (e.g. LCPagedMask) to put very large objects.
virtual TableRecord toRecord(const String& tableName) const;
// Convert to a WCBox from a record.
static WCBox* fromRecord (const TableRecord& rec,
const String& tableName);
// Returns WCBox
static String className();
// Return region type. Returns the class name
virtual String type() const;
private:
Vector<Quantum<Double> > itsBlc;
Vector<Quantum<Double> > itsTrc;
IPosition itsPixelAxes;
CoordinateSystem itsCSys;
Vector<Int> itsAbsRel;
Bool itsNull;
// Check units of quanta are consistent with CoordinateSystem
void checkUnits (const IPosition& pixelAxes,
const Vector<Quantum<Double> >& values,
const CoordinateSystem& cSys);
// Convert relative pixels to absolute or fill in defaults
void convertPixel(Double& pixel,
const Quantum<Double>& value,
const Int absRel,
const Double refPix,
const Int shape,
const Bool isBlc) const;
};
} //# NAMESPACE CASACORE - END
#endif
casacore::CoordinateSystem
Definition CoordinateSystem.h:215
casacore::IPosition
Definition IPosition.h:117
casacore::LCRegion
Definition LCRegion.h:86
casacore::Quantum
Definition Quantum.h:269
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore::TableRecord
Definition TableRecord.h:183
casacore::Vector
Definition Vector.h:82
casacore::WCBox::canExtend
virtual Bool canExtend() const
WCBox can extend a region.
casacore::WCBox::splitBox
WCBox splitBox(const IPosition &axes) const
Make a new box from the given axesin this box.
casacore::WCBox::itsPixelAxes
IPosition itsPixelAxes
Definition WCBox.h:369
casacore::WCBox::operator==
virtual Bool operator==(const WCRegion &other) const
Comparison.
casacore::WCBox::WCBox
WCBox()
casacore::WCBox::itsCSys
CoordinateSystem itsCSys
Definition WCBox.h:370
casacore::WCBox::toRecord
virtual TableRecord toRecord(const String &tableName) const
Convert the WCBox object to a record.
casacore::WCBox::itsBlc
Vector< Quantum< Double > > itsBlc
Definition WCBox.h:367
casacore::WCBox::fromRecord
static WCBox * fromRecord(const TableRecord &rec, const String &tableName)
Convert to a WCBox from a record.
casacore::WCBox::doToLCRegion
virtual LCRegion * doToLCRegion(const CoordinateSystem &cSys, const IPosition &latticeShape, const IPosition &pixelAxesMap, const IPosition &outOrder) const
Convert to an LCRegion using the supplied CoordinateSystem and shape.
casacore::WCBox::checkUnits
void checkUnits(const IPosition &pixelAxes, const Vector< Quantum< Double > > &values, const CoordinateSystem &cSys)
Check units of quanta are consistent with CoordinateSystem.
casacore::WCBox::WCBox
WCBox(const LCRegion &region, const CoordinateSystem &cSys)
Construct from the bounding box of an LCRegion.
casacore::WCBox::WCBox
WCBox(const Vector< Quantum< Double > > &blc, const Vector< Quantum< Double > > &trc, const CoordinateSystem &cSys, const Vector< Int > &absRel)
Construct from vectors of world coordinates defining the box corners.
casacore::WCBox::cloneRegion
virtual WCRegion * cloneRegion() const
Clone a WCBox object.
casacore::WCBox::~WCBox
virtual ~WCBox()
Destructor.
casacore::WCBox::WCBox
WCBox(const WCBox &other)
Copy constructor (reference semantics [except for CoordinateSystem]).
casacore::WCBox::itsNull
Bool itsNull
Definition WCBox.h:372
casacore::WCBox::WCBox
WCBox(const Vector< Quantum< Double > > &blc, const Vector< Quantum< Double > > &trc, const IPosition &pixelAxes, const CoordinateSystem &cSys, const Vector< Int > &absRel)
Construct from vectors of world coordinates defining the box corners.
casacore::WCBox::itsAbsRel
Vector< Int > itsAbsRel
Definition WCBox.h:371
casacore::WCBox::type
virtual String type() const
Return region type.
casacore::WCBox::convertPixel
void convertPixel(Double &pixel, const Quantum< Double > &value, const Int absRel, const Double refPix, const Int shape, const Bool isBlc) const
Convert relative pixels to absolute or fill in defaults.
casacore::WCBox::itsTrc
Vector< Quantum< Double > > itsTrc
Definition WCBox.h:368
casacore::WCBox::className
static String className()
Returns WCBox.
casacore::WCBox::operator=
WCBox & operator=(const WCBox &other)
Assignment (copy semantics).
casacore::WCRegion::WCRegion
WCRegion()
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::shape
IPosition shape(const RecordFieldId &) const
Get the actual shape of this field.
casacore::Int
int Int
Definition aipstype.h:48
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::value
NewDelAllocator< T > NewDelAllocator< T >::value
Definition Allocator.h:368
casacore::Double
double Double
Definition aipstype.h:53