WCPolygon.h

Classes

WCPolygon -- Class to define a 2-D polygonal world coordinate region in an image. (full description)

class WCPolygon : public WCRegion

Interface

Public Members

WCPolygon(const Quantum<Vector<Double> >& x, const Quantum<Vector<Double> >& y, const IPosition& pixelAxes, const CoordinateSystem& cSys, const RegionType::AbsRelType absRel=RegionType::Abs)

WCPolygon(const LCPolygon& polygon, const IPosition& pixelAxes, const CoordinateSystem& cSys)

WCPolygon (const WCPolygon& other)

virtual ~WCPolygon()

WCPolygon& operator= (const WCPolygon& other)

virtual Bool operator==(const WCRegion& other) const

virtual WCRegion* cloneRegion() const

virtual Bool canExtend() const

virtual LCRegion* doToLCRegion (const CoordinateSystem& cSys, const IPosition& latticeShape, const IPosition& pixelAxesMap, const IPosition& outOrder) const

virtual TableRecord toRecord(const String& tableName) const

static WCPolygon* fromRecord (const TableRecord& rec, const String& tableName)

static String className()

virtual String type() const

Private Members

void checkAxes (const IPosition& pixelAxes, const CoordinateSystem& cSys, const String& xUnit, const String& yUnit) const

void convertPixel(Double& pixel, const Double& value, const String& unit, const Int absRel, const Double refPix, const Int shape) const

static void unitInit()

Description

Prerequisite

Synopsis

The corners of the 2-D polygon are given by world coordinates. The vertices are connected by straight lines in lattice coordinates.

All this class does, apart from constructing itself, is know how to save itself to a Record and how to convert itself to an LCRegion. The conversion allows you to apply a WCPolygon constructed with one CoordinateSystem to another CoordinateSystem. That is, you can apply a WCPolygon from this image to that image.

At construction, it is assumed that the units of the world coordinates are the same as those encapsulated in the construction CoordinateSystem. You must tell the constructor, which world axes the x and vectors are associated with. Make sure you account for reordering. For example, if you reordered [ra,dec] to be [dec,ra] with the CoordinateSystem::transpose(,) fuction and wished the x vector to be ra, and the y vector to be dec, then worldAxes=[1,0].

The CoordinateSystem supplied to the toLCRegion (which returns a pointer to an LCPolygongon object) function does not have to be identical in structure to that with which the WCPolygon was constructed. However, each world axis given in the worldAxes vector at construction must be present somewhere (order is unimportant) in the supplied CoordinateSystem.

The supplied lattice shape must be 2-D and corresponds to the pixel axes of the two world axes of the supplied CoordinateSystem which match those of the construction CoordinateSystem.

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 polygon values don't matter. Similarly, the values of shape don't matter as long as there are 2 of them.

    cSys = [ra, dec, freq];
    cSys2 = [ra, dec];
    axes=[0,1];
    shape = [,];
    WCPolygon poly(x, y, axes, cSys);
    LCRegion* pR = poly.toLCRegion(cSys2, shape);

The resultant LCPolygon will have vertices converted with the [ra, dec] axes from cSys2

Example

    cSys = [ra, dec, freq];
    cSys2 = [ra, dec];
    axes=[0,2];
    shape = [,];
    WCPolygon poly(x, y, axes, cSys);
    LCRegion* pR = poly.toLCRegion(cSys2, shape);

This will throw an exception because the [freq] axis is missing in cSys2

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

    cSys = [ra, dec, freq];
    cSys2 = [stokes, freq, ra, dec], [3,2,1,0];
    axes=[1,2];
    shape = [,];
    WCPolygon poly(x, y, axes, cSys);
    LCRegion* pR = poly.toLCRegion(cSys2, shape);

The resultant LCPolygon will have vertices converted with the [ra, dec] axes from cSys2. The fact that the pixel axes of cSys2 were reordered is accounted for internally, but does not extrude further.

Example

In this example we make it a bit harder by remove a pixel axis.

    cSys = [ra, dec, freq];
    cSys2 = [stokes, freq, ra, dec];
    cSys2.removePixelAxis(1, cSys2.referencePixel()(1));
    axes=[1,2];
    shape = [,];
    WCPolygon poly(x, y, axes, cSys);
    LCRegion* pR = poly.toLCRegion(cSys2, shape);

This will throw an exception because the removed pixel axis, pixel axis number 1, corresponds to the [freq] world axis in cSys2, and the [freq] axis is one of those specified at construction. Although the world axis is still present, it is not possible to convert to a pixel coordinate if the pixel axis is not there.

Motivation

Users must be able to specify regions in world as well as lattice coordinates.

In all the constructors, you have to specifiy which plane the polygon lies in. You do this by specifying the *PIXEL AXES* (not the world axes) as this is the natural thing the user will want to specify.

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 CoordinateSystem for each axis.

World coordinates may be specified as absolute or offset. If the latter, they are offset with respect to the reference pixel of the CoordinateSystem.

To Do

Member Description

WCPolygon()

WCPolygon(const Quantum<Vector<Double> >& x, const Quantum<Vector<Double> >& y, const IPosition& pixelAxes, const CoordinateSystem& cSys, const RegionType::AbsRelType absRel=RegionType::Abs)

Construct from two vectors of world coordinates defining the polygon vertices.

WCPolygon(const LCPolygon& polygon, const IPosition& pixelAxes, const CoordinateSystem& cSys)

Construct from an LCPolygon.

WCPolygon (const WCPolygon& other)

Copy constructor (reference semantics).

virtual ~WCPolygon()

Destructor

WCPolygon& operator= (const WCPolygon& other)

Assignment (copy semantics)

virtual Bool operator==(const WCRegion& other) const

Comparison

virtual WCRegion* cloneRegion() const

Clone a WCPolygon object.

virtual Bool canExtend() const

WCPolygon cannot extend a region.

virtual LCRegion* doToLCRegion (const CoordinateSystem& cSys, const IPosition& latticeShape, const IPosition& pixelAxesMap, const IPosition& outOrder) const

Convert to an LCRegion using the given coordinate system.

virtual TableRecord toRecord(const String& tableName) const

Convert the WCPolygon object to a record. The record can be used to make the object persistent. The tableName argument can be used by derived classes (e.g. LCPagedMask) to put very large objects.

static WCPolygon* fromRecord (const TableRecord& rec, const String& tableName)

Convert to a WCPolygon from a record.

static String className()

Returns "WCPolygon"

virtual String type() const

Return region type. Returns the class name