This module defines a class for drawing shapes that define an area in your image. The drawing is interactive using mouse and keyboard buttons. For each defined area the module maputils calculates the sum of the intensities, the area and some other properties of the data. The shapes are one of polygon, ellipse, circle, rectangle or spline.
The strength of this module is that it duplicates a shape to other selected images using transformations to world coordinates. This enables one to compare e.g. flux in two images with different WCS systems. It works with spatial maps and maps with mixed axes (e.g. positionvelocity maps) and maps with linear axes. The order of the two axes in a map can be swapped.
Administration class for a collection of shapes. The figure
Parameters: 


This shape interactor reacts to the following keyboard and mouse buttons:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44  mouse  left : Drag a polygon point to a new position or
change the radius of a circle or
change the minor axis of an ellipse or
change the major axis and position angle of an ellipse
mouse  middle: Select an existing object in any frame
key  a : Add a point to a polygon or spline
key  c : Copy current object at mouse cursor
key  d : Delete a point in a polygon or spline
key  e : Erase active object and associated objects in other images
key  i : Insert a point in a polygon or spline
key  n : Start with a new object
key  u : Toggle markers. Usually for a hardcopy
one does not want to show the markers of a shape.
key  w : Write object data in current image to file on disk
key  r : Read objects from file for current image
key  [ : Next active object in current shape selection
key  ] : Previous active object in current shape selection
Interactive navigation defined by canvas
Amongst others:
key  f : Toggle fullscreen
key  g : Toggle grid
Gui buttons:
'Quit' : Abort program
'plot result' : Plot calculated flux as function of shape and image
'Save result' : Save flux information to disk
The file names are generated and contain date
and time stamp (e.g flux_24042010_212029.dat)
'Pol.' : Select shape polygon. Start with key 'n' for
new polygon. Add new points with key 'a'.
'Ell.' : Select shape ellipse. Start with key 'n' for
new ellipse. With left mouse button Drag major axis to change
size and rotation or, using a point near the
center, drag entire ellipse to a new position.
'Cir.:' : Select shape circle. Start with key 'n' for
new circle. The radius can be changed by dragging
an arbitrary point on the border to a new position.
'Rec.' : Select shape rectangle. Start with key 'n' for
new rectangle. Drag any of the four edges to resize
the rectangle.
'Spl.' : Like the polygon but the points between two knots
follow a spline curve.

Notes:  All shapes are derived from a polygon class. There is one method that generates coordinates for all shapes and maputils.getflux() uses the same routine to calculate whether a pixel in an enclosing box is within or outside the shape. For circles and ellipses the number of polygon points is 360 and this slows down the calculation significantly. Methods which assume a perfect circle or ellipse can handle the inside/outside problem much faster, but note that due to different WCS’s, ellipses and circles don’t keep their shape in other images. So in fact only a polygon is the common shape. A spline is a polygon with an artificially increased number of points. 


Example: 

Get sample positions on ellipse Algorithm from ‘Mathematical Elements for Computer Graphics’ by Rogers and Adams, section about ‘Parametric Representation of an Ellipse’ Many methods which calculate sample positions on an ellipse suffer from a reasonable sampling near the positions where the curvature of an ellipse is large. The method we use, finds more sample points near the end points of an ellipse where the curvature is large while the increment between sample points along the sides of the ellipse where the curvature is not large, is small
For an ellipse centered at (0,0), semimajor axis a and semiminor axis b the parametric representation is given by:
x = a * cos(th)
y = b * sin(th)
‘th’ is the parameter and it represents the angle between 0 and 2*pi One can derive a recursive relation:
x_i+1 = x_i cos(dth)  (a/b) y_i sin(dth)
y_i+1 = (b/a) x_i sin(dth) + y_i cos(dth)
dth is a step size in the angle th. It is equal to 2*pi/(n1) n1 is the required number or unique points on the ellipse and therefore an input parameter. The routine returns a result which is empty when either a or b is zero.
The shift of the origin and the rotation of the ellipse can be combined into one matrix:
 cos(a) sin (a) 0   1 0 0 
T = sin(a) cos (a) 0   0 1 0 
 0 0 1   xc yc 1 
Finally the result is computed with:
X, Y, dummy = (x, y, 1).T
The result is a polygon which describes the maximum inscribed area for the given ellipse parameters (Smith, L.B., “Drawing Ellipses, Hyperbolas, or Parabolas With a Fixed Number of Points and Maximum Inscribed Area,” Comp. J., Vol. 14, pp. 8186, 1969
Parameters: 


Notes:  The ‘classical’ method involves the calculation of many cosine and sine functions. This method avoids that by using a method which calculates a new sample based on the information of a previous sample. However, we didn’t find a way to do this properly using NumPy. The classic method is very suitable to do implement in NumPy and is therefore faster than the algorithm here. But the sampling is better and we can do with less samples to get the same result. 