Module rulers

This module defines a class for drawing rulers.

class kapteyn.rulers.Ruler(projection, mixpix, pxlim, pylim, aspectratio=1.0, pos1=None, pos2=None, rulersize=None, rulerangle=None, x1=None, y1=None, x2=None, y2=None, lambda0=0.5, step=None, world=False, angle=None, addangle=0.0, fmt=None, fun=None, units=None, fliplabelside=False, mscale=None, labelsintex=True, gridmode=False, **kwargs)[source]

Draws a line between two spatial positions from a start point (x1,y1) to an end point (x2,y2) with labels indicating a constant offset in world coordinates. The positions are either in pixels or in world coordinates. The start and end point can also be positions entered as a string which follows the syntax described in method kapteyn.positions.str2pos(). The ruler can also be given as a start point and a size and angle. These are distance and angle on a sphere.

The ruler is a straight line but the ticks are usually not equidistant because projection effects make the offsets non linear (e.g. the TAN projection diverges while the CAR projection shows equidistant ticks). By default, the zero point is exactly in the middle of the ruler but this can be changed by setting a value for lambda0. The step size for the ruler ticks in units of the spatial axes is entered in parameter step. At least one of the axes in the plot needs to be a spatial axis.

Size and step size can be entered in units given by a parameter units. The default unit is degrees.

Parameters:

  • projection (A wcs.Projection object) – The Projection object which sets the WCS for the ruler.

  • mixpix (Integer) – The pixel of the missing spatial axis in a Position-Velocity image.

  • pxlim (Tuple or list with two integers.) – Limit in pixel coordinates for the x-axis.

  • pylim (Tuple or list with two integers.) – Limit in pixel coordinates for the y-axis.

  • aspectratio (Float) – The aspect ratio is defined as pixel height / pixel width. The value is needed to draw tick mark perpendicular to the ruler line for images where the pixels are not square in world coordinates. Its default is 1.0.

  • pos1 (String) – Position information for the start point. This info overrules the values in x1 and y1.

  • pos2 (String) – Position information for the end point. This info overrules the values in x2 and y2.

  • rulersize (Floating point number) – Instead of entering a start- and an end point, one can also enter a start point in pos1 or in x1, y1 and specify a size of the ruler. The size is entered in units given by parameter units. If no units are given, the size is in degrees. Note that with size we mean the distance on a sphere. To calculate the end point, we need an angle. this angle is given in rulerangle. If rulersize has a value, then values in pos2 and x2,y2 are ignored.

  • rulerangle (Floating point number) – An angel in degrees which, together with rulersize, sets the end point of the ruler. The angle is defined as an angle on a sphere. The angle is an astronomical angle (defined with respect to the direction of the North).

  • x1 (None or Floating point number) – X-location of start of ruler either in pixels or world coordinates Default is lowest pixel coordinate in x.

  • y1 (None or Floating point number) – Y-location of start of ruler either in pixels or world coordinates Default is lowest pixel coordinate in y.

  • x2 (None or Floating point number) – X-location of end of ruler either in pixels or world coordinates Default is highest pixel coordinate in x.

  • y2 (None or Floating point number) – Y-location of end of ruler either in pixels or world coordinates Default is highest pixel coordinate in y.

  • lambda0 (Floating point number) – Set the position of label which represents offset 0.0. Default is lambda=0.5 which represents the middle of the ruler. If you set lambda=0 then offset 0.0 is located at the start of the ruler. If you set lambda=1 then offset 0.0 is located at the end of the ruler.

  • step (Floating point number) – Step size of world coordinates in degrees or in units entered in units.

  • world (Boolean) – Set ruler mode to world coordinates (default is pixels)

  • angle (Floating point number) – Set angle of tick marks in degrees. If omitted then a default is calculated (perpendicular to ruler line) which applies to all labels.

  • addangle – Add a constant angle in degrees to angle. Only useful if angle has its default value. This parameter is used to improve layout.

  • fmt (String) – Format of the labels. See example. Do not use TeX’s $ characters because these will be appended when processing the labels.

  • fun (Python function or Lambda expression) – Format ruler values according to this function (e.g. to convert degrees into arcminutes). The output is always in degrees.

  • units (String) –

    Rulers ticks are labeled in a unit that is compatible with degrees. The units are set by the step size used to calculate the position of the tick marks. You can set these units explicitely with this parameter. Note that values for fun and fmt cannot be set because these are set automatically if units has a value. Note that units needs only a part of a complete units string because a case insensitive minimal match is applied. Usually one will use something like units=arcmin or units=Arcsec.

    Note: If a value for units is entered, then this method expects the step size is given in the same units.

  • fliplabelside (Boolean) – Choose other side of ruler to draw labels.

  • mscale (Floating point number) – A scaling factor to create more or less distance between the ruler and its labels. If None then this method calculates defaults. The values are usually less than 5.0.

  • gridmode (Boolean) – If True, correct pixel position for CRPIX to get grid coordinates where the pixel at CRPIX is 0

  • **kwargs (Matplotlib keyword argument(s)) – Set keyword arguments for the labels. The attributes for the ruler labels are set with these keyword arguments.

Raises:
Exception

Rulers only suitable for maps with at least one spatial axis! These rulers are only for plotting offsets as distances on a sphere for the current projection system. So we need at least one spatial axis and if there is only one spatial axis in the plot, then we need a matching spatial axis.

Exception

Cannot make ruler with step size equal to zero! Either the input of the step size is invalid or a wrong default was calculated (perhaps end point is equal to start point).

Exception

Start point of ruler not in pixel limits!

Exception

End point of ruler not in pixel limits!

Returns:

A ruler object of class ruler which is added to the plot container with Plotversion’s method Plotversion.add(). This ruler object has two methods to change the properties of the line and the labels:

  • setp_line(**kwargs) – Matplotlib keyword arguments for changing

    the line properties.

  • setp_labels(**kwargs) – Matplotlib keyword arguments for changing

    the label properties.

Notes:

A bisection is used to find a new marker position so that the distance to a previous position is step.. We use a formula of Thaddeus Vincenty, 1975, for the calculation of a distance on a sphere accurate over the entire sphere.

Examples:

Create a ruler object and change its properties

ruler2 = annim.Ruler(x1=x1, y1=y1, x2=x2, y2=y2, lambda0=0.5, step=2.0,
                     fmt='%3d', mscale=-1.5, fliplabelside=True)
ruler2.setp_labels(ha='left', va='center', color='b')

ruler4 = annim.Ruler(pos1="23h0m 15d0m", pos2="22h0m 30d0m", lambda0=0.0,
                     step=1, world=True,
                     fmt=r"%4.0f^\prime",
                     fun=lambda x: x*60.0, addangle=0)
ruler4.setp_line(color='g')
ruler4.setp_labels(color='m')

# Force step size and labeling to be in minutes of arc.
annim.Ruler(pos1='0h3m30s 6d30m', pos2='0h3m30s 7d0m',
            lambda0=0.0, step=5.0,
            units='arcmin', color='c')
setp_line(**kwargs)[source]

Set the ruler line properties. The keyword arguments are Matplotlib keywords for Line2D objects.

Parameters:

kwargs (Python keyword arguments) – Keyword argument(s) for changing the default properties of the ruler line. This line is a Line2D Matplotlib object with attributes like linewidth, color etc.

setp_label(**kwargs)[source]

Set the ruler label properties. The keyword arguments are Matplotlib keywords for Text objects. Note that the properties apply to all labels. It is not possible to address a separate label.

Parameters:

kwargs (Python keyword arguments) – Keyword argument(s) for changing the default properties of the ruler labels. This line is a Text Matplotlib object with attributes like fontsize, color etc.