B.1.17 Sky

Functions useful for working with shapes on a sphere. All angles are expressed in degrees.

skyDistance( lon1, lat1, lon2, lat2 )

Calculates the separation (distance around a great circle) of two points on the sky in degrees.

This function is identical to skyDistanceDegrees in class CoordsDegrees.

• Parameters:
  • lon1 (floating point): point 1 longitude in degrees
  • lat1 (floating point): point 1 latitude in degrees
  • lon2 (floating point): point 2 longitude in degrees
  • lat2 (floating point): point 2 latitude in degrees
• Return value
  • (floating point): angular distance between point 1 and point 2 in degrees

midLon( lon1, lon2 )

Determines the longitude mid-way between two given longitudes. In most cases this is just the mean of the two values, but this function copes correctly with the case where the given values straddle the lon=0 line.

• Parameters:
  • lon1 (floating point): first longitude in degrees
  • lon2 (floating point): second longitude in degrees
• Return value
  • (floating point): longitude midway between the given values
• Examples:
  • midLon(204.0, 203.5) = 203.75
  • midLon(2, 359) = 0.5

midLat( lat1, lat2 )

Determines the latitude midway between two given latitudes. This simply returns the mean of the two values, but is supplied for convenience to use alongside the midLon function.

• Parameters:
  • lat1 (floating point): first latitude in degrees
  • lat2 (floating point): second latitude in degrees
• Return value
  • (floating point): latitude midway between the given values
• Example:
  • midLat(23.5, 24.0) = 23.75

inSkyEllipse( lon0, lat0, lonCenter, latCenter, rA, rB, posAng )

Tests whether a given sky position is inside a given ellipse.

• Parameters:
  • lon0 (floating point): test point longitude in degrees
  • lat0 (floating point): test point latitude in degrees
  • lonCenter (floating point): ellipse center longitude in degrees
  • latCenter (floating point): ellipse center latitude in degrees
  • rA (floating point): ellipse first principal radius in degrees
  • rB (floating point): ellipse second principal radius in degrees
  • posAng (floating point): position angle in degrees from the North pole to the primary axis of the ellipse in the direction of increasing longitude
• Return value
  • (boolean): true iff test point is inside, or on the border of, the ellipse

inSkyPolygon( lon0, lat0, lonLats, ... )

Tests whether a given sky position is inside the polygon defined by a given set of vertices. The bounding lines of the polygon are the minor arcs of great circles between adjacent vertices, with an extra line assumed between the first and last supplied vertex. The interior of the polygon is defined to be the smaller of the two regions separated by the boundary. The vertices are specified as a sequence of lon_i, lat_i pairs.

The implementation of this point-in-polygon function is mostly correct, but may not be bulletproof. It ought to work for relatively small regions anywhere on the sky, but for instance it may get the sense wrong for regions that extend to cover both poles.

• Parameters:
  • lon0 (floating point): test point latitude in degrees
  • lat0 (floating point): test point longitude in degrees
  • lonLats (floating point, one or more): 2N arguments (lon1, lat1, lon2, lat2, ..., lonN, latN) giving (longitude, latitude) vertices of an N-sided polygon in degrees
• Return value
  • (boolean): true iff test point is inside, or on the border of, the polygon