cds.astro
Class QboxNumber

java.lang.Object
  cds.astro.QboxNumber

All Implemented Interfaces:

java.io.Serializable

public class QboxNumber
extends java.lang.Object
implements java.io.Serializable

The QboxNumber is just a number representing a cell of the celestial sphere. This number is used in Qbox and QboxIndex classes.

A qbox number is formed by the values of the projections (X,Y) of the directions on the 6 faces of a cube numbered 1 (z=1), 2 (y=1), 3 (x=1), 4 (x=-1), 5 (y=-1) and 6 (z=-1).

The faces and orientations are defined as:

 
                  +---------+
                  |    ^    |
                  |    |    |
                  |   1+--->|
                  |      x  |
                  |         |
        +---------+---------+---------+---------+
        |    ^    |    ^    |         |         |
        |    |    |    |    |         |         |
        |   5+--->|  3 +--->|   2+--->|   4+--->|
        |      x  |      x  |   x|    |   x|    |
        |         |         |    v    |    v    |
        +---------+---------+---------+---------+
                  |    ^    |
                  |    |x   |
                  |<---+    |
                  |    6    |
                  |         |
                  +---------+
 

Each cube face is divided into 4 areas; each area is further divided into four pieces, etc. The number of valid qboxes is 6×4^N:

   Level    Lower #      qboxes   qbox_size
      0           9           6     83º
      1          36          24     41º
      2         144          96     20º
      3         576         384     10º
      4        2304        1536      5º
      5        9216        6144      2º30'
      6       36864       24576      1º15'
      7      147456       98304        40'
      8      589824      393216        20'
      9     2359296     1572864        10'
     10     9437184     6291456         5'
     11    37748736    25165824         2'30"
     12   150994944   100663296         1'15"
 

where level is a number which can be changed at any time using setLevel(level) method.

The present implementation assumes that level<=12, corresponding to a maximum of 28 bits in the qbox number.

For a level 6, the qbox number is a short integer with bits (from left to right) 1ppp xyxy xyxy xyxy. The leftmost `1' bit allows the recognition of the level; bits p represent the face number (1 to 6), x and y the position, expressed with level bits, along the axises defined above for the face; going one level down in the hierarchy is therefore just a shift of 2 bits and updating the 2 rightmost bits.

See Also:

Serialized Form

Field Summary

static int	default_level Default level used in QboxNumber(), (default 9 or size about 10')
int	level Level of the chosen Qboxes (for creation), between 0 and 12

Constructor Summary

QboxNumber()
Class of Qbox numbers with default level.

QboxNumber(double arcmin)
Class of Qbox numbers with a specified resolution.

QboxNumber(int level)
Class of Qbox numbers with a specified level

Method Summary

static int	adjacent(int qboxno, int direction) Find the adjacent qbox in the specified direction.
static double	area(int qbox) Compute the area (in square degrees) of a Qbox.
static Coo	center(int qbox) Get the central position of a Qbox
static void	center(int qbox, Coo coo) Set the central position of a Qbox
static int	face(int qbox) Face number on which the qbox is located.
static int	index(int qbox) Interpret the qbox as an index (offset) number.
static int	level(int qbox) Derive the level of a Qbox number.
double	maxRadius() Radius of circle containing any Qbox.
double	minRadius() Radius of circle included in any Qbox.
int	nearby(Coo center, int[] contig, double[] sin2d2) Identifies the 9 qboxes close to a target position.
static void	nearby(int qboxno, int[] contig) Identifies the 8 qboxes contiguous to one qbox.
int	qbox(Coo c) Identifies the Qbox containing a given position.
int	qbox(Coocube cc) Identifies the Qbox containing a position given by a Coocube.
int	qbox(double lon, double lat) Identifies the Qbox containing a position given by RA and Dec.
static int	qbox(java.lang.String text) Interpret an edited Qbox number (see toString(int))
static double	radius(int qbox) Compute radius (degrees) of the Circle including a Qbox.
static int	setLevel(int lev) Change the default level.
java.lang.String	toString() Edition of Qbox level
static java.lang.String	toString(int qbox) Edition of a Qbox value

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

level

public final int level

Level of the chosen Qboxes (for creation), between 0 and 12

default_level

public static int default_level

Default level used in QboxNumber(), (default 9 or size about 10')

Constructor Detail

QboxNumber

public QboxNumber()

Class of Qbox numbers with default level. Notice that the static default level may be changed with the setLevel(int) method.

QboxNumber

public QboxNumber(int level)

Class of Qbox numbers with a specified level

Parameters:

level - the level to use as default Notice that the static default level may be changed with the setLevel method.

QboxNumber

public QboxNumber(double arcmin)

Class of Qbox numbers with a specified resolution. The level computed is such that any source having a diameter up to arcmin is not larger than a Qbox, i.e. requires to look only at the target Qbox and its neighbours (see nearby(int, int[]))

Parameters:

arcmin - resolution, in arcmin.

Method Detail

setLevel

public static final int setLevel(int lev)

Change the default level. It is a change of the static default_level variable. This means that the creation of a class from the default QboxNumber() will use the specified level.

Parameters:

lev - the default level, between 0 and 12. Values outside the [0..12] range are ignored.

Returns:

the previously defined default level

qbox

public static int qbox(java.lang.String text)
                throws java.text.ParseException

Interpret an edited Qbox number (see toString(int))

Parameters:

text - The text to interpret

Throws:

java.text.ParseException - when the text contains invalid characters

level

public static final int level(int qbox)

Derive the level of a Qbox number.

Parameters:

qbox - a Qbox number.

Returns:

the level corresponding to the integer (between -1 and 12)

index

public static final int index(int qbox)

Interpret the qbox as an index (offset) number.

Parameters:

qbox - a Qbox number.

Returns:

a number between 0 and 6×4^N-1 which can be used e.g. as an index in an array.

face

public static final int face(int qbox)

Face number on which the qbox is located.

Returns:

the face number, between 1 and 6 . A value of 0 is returned when qbox=0 (whole sphere)

qbox

public final int qbox(double lon,
                      double lat)

Identifies the Qbox containing a position given by RA and Dec.

Parameters:

lon - the longitude (RA), degrees

lat - the latitude (Dec), degrees

qbox

public final int qbox(Coocube cc)

Identifies the Qbox containing a position given by a Coocube.

Parameters:

cc - the Coocube equivalent of the position

qbox

public final int qbox(Coo c)

Identifies the Qbox containing a given position.

Parameters:

c - the Coocube equivalent of the position

center

public static final Coo center(int qbox)

Get the central position of a Qbox

Parameters:

qbox - a Qbox number

center

public static final void center(int qbox,
                                Coo coo)

Set the central position of a Qbox

Parameters:

qbox - a Qbox number

coo - a Coo, filled with the position.

maxRadius

public final double maxRadius()

Radius of circle containing any Qbox. It is the radius of a small circle centered at a Qbox center which includes any Qbox (at level).

Returns:

The maximal radius

minRadius

public final double minRadius()

Radius of circle included in any Qbox. It is the radius of a small circle centered at a Qbox center which is completely included within any Qbox (at level).

Returns:

The minimal radius

area

public static final double area(int qbox)

Compute the area (in square degrees) of a Qbox. Use the ArcSin formula S = A_0 + A_1 + A_2 + A_3 - 2*pi where A_i are the angles of the rectangle. The formula is especially simple in a tangential projection.

Parameters:

qbox - the Qbox number

Returns:

The area for the Qbox in square degrees.

radius

public static final double radius(int qbox)

Compute radius (degrees) of the Circle including a Qbox.

Parameters:

qbox - the Qbox number

Returns:

The radius of a circle centered at the Qbox center and containing the Qbox.

adjacent

public static final int adjacent(int qboxno,
                                 int direction)

Find the adjacent qbox in the specified direction.

Parameters:

qboxno - the starting qbox

direction - A direction, as a number 0 to 3. The direction has the values 0=+x 1=+y 2=-y 3=-x

Returns:

the qbox (at the same level) contiguous in the specified direction.

nearby

public static final void nearby(int qboxno,
                                int[] contig)

Identifies the 8 qboxes contiguous to one qbox.

Parameters:

qboxno - the starting qbox

contig - [8] the eight contiguous qboxes. The 8 contiguous qboxes are given in the following order:

    +---+---+---+
    | 7 | 1 | 4 |
    +---+---+---+
    | 3 | . | 0 |
    +---+---+---+
    | 6 | 2 | 5 |
    +---+---+---+
 

Notice that near the corners, only 7 contiguous qboxes exist; the value of the missing qbox is set to 0. And at the zero level (i.e. only 6 qbxoes) there are only 4 contiguous qboxes.

nearby

public final int nearby(Coo center,
                        int[] contig,
                        double[] sin2d2)

Identifies the 9 qboxes close to a target position.

Parameters:

center - a Coo position

contig - [9] the 9 neighbouring qboxes, ordered by increasing distance fom center

sin2d2 - [9] closest squared distance (in SIN2 projection where r=2.sin(r/2)). The actual distance between center and contig[i] (in degrees) can be computed as r = 2. * AstroMath.asind(0.5 * Math.sqrt(sin2d2))

Returns:

Number of qboxes (5, 8 or 9) in the contig and in2d2 arrays.

toString

public static final java.lang.String toString(int qbox)

Edition of a Qbox value

Returns:

the string equivalent of the coocube the letter 'A' is appended for ANY IN QBOX.

toString

public final java.lang.String toString()

Edition of Qbox level

Overrides:

toString in class java.lang.Object

Returns:

a string.