# Class Coverage

java.lang.Object
uk.ac.starlink.ttools.func.Coverage

public class Coverage extends Object
Functions related to coverage and footprints.

One coverage standard is Multi-Order Coverage maps, described at http://www.ivoa.net/Documents/MOC/. MOC positions are always defined in ICRS equatorial coordinates.

MOCs may be specified using a string argument of the functions in one of the following ways:

- The filename of a MOC FITS file
- The URL of a MOC FITS file
- The identifier of a VizieR table, for instance "`V/139/sdss9`" (SDSS DR9)
- An ASCII MOC string, for instance "`1/1 2 4 2/12-14 21 23 25 8/`"

A list of all the MOCs available from VizieR can currently be found at http://alasky.u-strasbg.fr/footprints/tables/vizier/. You can search for VizieR table identifiers from the VizieR web page (http://vizier.u-strasbg.fr/); note you must use the table identifier (like "`V/139/sdss9`") and not the catalogue identifier (like "`V/139`").

Since:
  29 May 2012
Author:
  Mark Taylor

## Field Summary

Fields
Modifier and Type
Field
Description
`static final double`
`SPHERE_SQDEG`
The number of square degrees on the sphere, approx 41253.
`static final double`
`SPHERE_STERADIAN`
The number of steradians on the sphere, 4 PI.

## Method Summary

Modifier and Type
Method
Description
`static boolean`
`inMoc(String moc, double ra, double dec)`
Indicates whether a given sky position falls strictly within a given MOC (Multi-Order Coverage map).
`static double`
`mocSkyProportion(String moc)`
Returns the proportion of the sky covered by a given MOC.
`static long`
`mocTileCount(String moc)`
Returns the number of unique tiles within a given MOC.
`static long`
`mocUniq(int order, long index)`
Converts a HEALPix order and and tile index into a UNIQ-encoded integer as used in MOC encoding.
`static boolean`
`nearMoc(String moc, double ra, double dec, double distanceDeg)`
Indicates whether a given sky position either falls within, or is within a certain distance of the edge of, a given MOC (Multi-Order Coverage map).
`static long`
`uniqToIndex(long uniq)`
Extracts the HEALPix pixel index from a UNIQ-encoded integer as used in MOC encoding.
`static int`
`uniqToOrder(long uniq)`
Extracts the HEALPix order from a UNIQ-encoded integer as used in MOC encoding.

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### SPHERE_STERADIAN

public static final double SPHERE_STERADIAN
The number of steradians on the sphere, 4 PI.

See Also:
  - Constant Field Values

### SPHERE_SQDEG

public static final double SPHERE_SQDEG
The number of square degrees on the sphere, approx 41253.

See Also:
  - Constant Field Values

## Method Details

### inMoc

public static boolean inMoc(String moc, double ra, double dec)
Indicates whether a given sky position falls strictly within a given MOC (Multi-Order Coverage map). If the given `moc` value does not represent a MOC (for instance no file exists or the file/string is not in MOC format) a warning will be issued the first time it's referenced, and the result will be false.

Parameters:
  `moc` - a MOC identifier; a filename, a URL, a VizieR table name, or an ASCII MOC string
  `ra` - ICRS right ascension in degrees
  `dec` - ICRS declination in degrees
Returns:
  true iff the given position falls within the given MOC

### nearMoc

public static boolean nearMoc(String moc, double ra, double dec, double distanceDeg)
Indicates whether a given sky position either falls within, or is within a certain distance of the edge of, a given MOC (Multi-Order Coverage map). If the given `moc` value does not represent a MOC (for instance no file exists or the file/string is not in MOC format) a warning will be issued the first time it's referenced, and the result will be false.

Parameters:
  `moc` - a MOC identifier; a filename, a URL, a VizieR table name, or an ASCII MOC string
  `ra` - ICRS right ascension in degrees
  `dec` - ICRS declination in degrees
  `distanceDeg` - permitted distance from MOC boundary in degrees
Returns:
  true iff the given position is within `distance` degrees of the given MOC

### mocSkyProportion

public static double mocSkyProportion(String moc)
Returns the proportion of the sky covered by a given MOC.

If the given `moc` value does not represent a MOC (for instance no file exists or the file/string is not in MOC format) a warning will be issued the first time it's referenced, and the result will be NaN.

Parameters:
  `moc` - a MOC identifier; a filename, a URL, a VizieR table name, or an ASCII MOC string
Returns:
  a fractional value in the range 0..1

### mocTileCount

public static long mocTileCount(String moc)
Returns the number of unique tiles within a given MOC.

If the given `moc` value does not represent a MOC (for instance no file exists or the file/string is not in MOC format) a warning will be issued the first time it's referenced, and the result will be 0.

Parameters:
  `moc` - a MOC identifier; a filename, a URL, a VizieR table name, or an ASCII MOC string
Returns:
  number of tiles in the MOC

### mocUniq

public static long mocUniq(int order, long index)
Converts a HEALPix order and and tile index into a UNIQ-encoded integer as used in MOC encoding. The result is `index + 4**(1+order)`.

If the order or index are out of bounds, behaviour is undefined.

Parameters:
  `order` - HEALPix order, in range 0..29
  `index` - tile index within the given level
Returns:
  uniq-encoded value

### uniqToOrder

public static int uniqToOrder(long uniq)
Extracts the HEALPix order from a UNIQ-encoded integer as used in MOC encoding.

If the supplied value is not a legal UNIQ integer, behaviour is undefined.

Parameters:
  `uniq` - uniq-encoded value
Returns:
  HEALPix order

### uniqToIndex

public static long uniqToIndex(long uniq)
Extracts the HEALPix pixel index from a UNIQ-encoded integer as used in MOC encoding.

If the supplied value is not a legal UNIQ integer, behaviour is undefined.

Parameters:
  `uniq` - uniq-encoded value
Returns:
  pixel index