cds.astro
Class Qbox

java.lang.Object
  extended by cds.astro.Qbox
All Implemented Interfaces:
java.io.Serializable

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

The Qbox divides the celestial sphere into "cells" of approximative constant size. The routines provided in this module all deal with "qboxes". A qbox is just a number which represents one of the cells.

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×4N:
   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.

The selection of valid qboxes makes usage of an Enumeration which returns the valid qboxes via its nextElement method.

See Also:
Serialized Form

Field Summary
static int level
           
 
Constructor Summary
Qbox()
          Define the default Qbox which represents the whole sphere
Qbox(Coo coo)
          Define the Qbox containing a given position, at the current level.
Qbox(Qbox qb)
          Copy constructor.
Qbox(java.lang.String text)
          Define the Qbox from a text similar to the Edited qbox (see toString)
 
Method Summary
 double area()
          Compute the area (in square degrees) of a Qbox.
 int box()
          Actual qbox value as an Integer
 Coocube center()
          Convert a Qbox into the Coocube position of its center.
static java.util.Enumeration circle(Coo center, double radius)
           
 Coo[] corners()
          Get the 4 corners of a Qbox.
static int corners(int qboxno, double[] blur)
          Compute the Corners of a Qbox from qbox number
 boolean equals(java.lang.Object o)
          MOD-BB 21-01-04 Ajout de cette methode.
 int face()
          On which face is located the qbox ?
 int index()
          Actual qbox index
 boolean inside(Coo point)
          Tests whether a point is inside a Qbox
 boolean isAny()
          Status of a Qbox: check whether it's completely included in the Selection (no need to make further tests on Position)
 int level()
          Actual qbox level
static int level(int b)
          Compute the level of any integer considered as a qbox
 java.util.Enumeration list()
          List in an enumeration all Qboxes corresponding to a qbox To get all qboxes, just do the following: cq = new Qbox(); e=cq.list();
static java.util.Enumeration list(java.util.ArrayList vector)
          List in an enumeration all Qboxes selected in a ArrayList
static java.util.Enumeration list(Region region)
          Return all Qboxes concerned by a Region (circle, box, zone, etc...)
static double maxRadius()
          Return the maximal radius (in degrees) of any Qbox at the default level
static double maxRadius(int qbox)
          Return the maximal radius (in degrees) of a Qbox
static double minRadius()
          Return the minimal radius (in degrees) of a Qbox.
static double minRadius(int qbox)
          Return the minimal radius (in degrees) of any Qbox at the default level
 double radius()
          Compute the radius (in degrees) of the Circle containing the Qbox.
 void set(Coo c)
          Convert a Position into its Qbox at the default level
 void set(Coocube cc)
          Convert a Coocube into a Qbox at the default level
 void set(Qbox qb)
          Sets the Qbox value from another Qbox object
static int setLevel(int lev)
          Change the default Level which is 9.
 void toAny()
          Set the Qbox to the 'Any' status.
 java.lang.String toString()
          Default Edition of the Qbox value
static int ucenter(int qboxno, double[] ucenter)
          Compute the unit vector of the center of a Qbox.
static int ucorners(int qboxno, double[][] ucorn)
          Compute the 4 vectors representing the corners of a Qbox.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

level

public static int level
Constructor Detail

Qbox

public Qbox()
Define the default Qbox which represents the whole sphere


Qbox

public Qbox(Qbox qb)
Copy constructor.

Parameters:
qb - Qbox object to copy

Qbox

public Qbox(Coo coo)
Define the Qbox containing a given position, at the current level.

Parameters:
coo - coordinates object used to create the Qbox

Qbox

public Qbox(java.lang.String text)
     throws java.text.ParseException
Define the Qbox from a text similar to the Edited qbox (see toString)

Parameters:
text - The text to interpret
Throws:
java.text.ParseException - when the text contains invalid characters
Method Detail

setLevel

public static final int setLevel(int lev)
Change the default Level which is 9.

Parameters:
lev - the new level, between 0 and 12 -- other values do not change it.
Returns:
the previously defined level

corners

public static final int corners(int qboxno,
                                double[] blur)
Compute the Corners of a Qbox from qbox number

Parameters:
qboxno - the qbox number
blur - the (xy) position of Bottom-Left and Up-Right points in the tangential projection.
Returns:
the cube face number in range 1..6 (0 if full sky or error)

ucenter

public static final int ucenter(int qboxno,
                                double[] ucenter)
Compute the unit vector of the center of a Qbox.

Parameters:
qboxno - the qbox number
ucenter - a [3] array containing on return the unit vector
Returns:
the cube face number in range 1..6 (0 if error)

ucorners

public static final int ucorners(int qboxno,
                                 double[][] ucorn)
Compute the 4 vectors representing the corners of a Qbox. The corners are stored in the direct (trigonometric) order.

Parameters:
qboxno - the qbox number
ucorn - a [4][3] array of vertices vector.
Returns:
the cube face number in range 1..6 (0 if error)

level

public static final int level(int b)
Compute the level of any integer considered as a qbox

Parameters:
b - the integer considered as a Qbox.
Returns:
the level corresponding to the integer (between -1 and 13)

level

public final int level()
Actual qbox level

Returns:
the level corresponding to the qbox (between -1 and 12)

isAny

public final boolean isAny()
Status of a Qbox: check whether it's completely included in the Selection (no need to make further tests on Position)

Returns:
true if the box is "any"

toAny

public final void toAny()
Set the Qbox to the 'Any' status. the Selection (no need to make further tests on Position)


box

public final int box()
Actual qbox value as an Integer

Returns:
a box value (in the range specified in the introduction)

index

public final int index()
Actual qbox index

Returns:
the index, a number between 0 and 6*4^level -1; -1 for uninitialized qbox (no position).

face

public final int face()
On which face is located the qbox ?

Returns:
the face number, between 1 and 6 -- 0 for whole sphere

set

public final void set(Coocube cc)
Convert a Coocube into a Qbox at the default level

Parameters:
cc - the Coocube equivalent of the position

set

public final void set(Qbox qb)
Sets the Qbox value from another Qbox object

Parameters:
qb - Qbox object to copy

set

public final void set(Coo c)
Convert a Position into its Qbox at the default level

Parameters:
c - the Coocube equivqlent of the position

center

public final Coocube center()
Convert a Qbox into the Coocube position of its center.


inside

public final boolean inside(Coo point)
Tests whether a point is inside a Qbox

Parameters:
point - a point to test
Returns:
true is the point is inside the Qbox

maxRadius

public static final double maxRadius()
Return the maximal radius (in degrees) of any Qbox at the default level

Returns:
The maximal radius

maxRadius

public static final double maxRadius(int qbox)
Return the maximal radius (in degrees) of a Qbox

Parameters:
qbox - a valid qbox number
Returns:
The maximal radius (circle includes the Qbox)

minRadius

public static final double minRadius()
Return the minimal radius (in degrees) of a Qbox.

Returns:
The minimal radius (circle fully included in Qbox)

minRadius

public static final double minRadius(int qbox)
Return the minimal radius (in degrees) of any Qbox at the default level

Parameters:
qbox - a valid qbox number
Returns:
The minimal radius (circle fully included in Qbox)

area

public final double area()
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.

Returns:
The area for the Qbox in square degrees.

radius

public final double radius()
Compute the radius (in degrees) of the Circle containing the Qbox.

Returns:
The radius of the Qbox

corners

public final Coo[] corners()
Get the 4 corners of a Qbox.

Returns:
the 4 coordinates (which define a rectangle)

toString

public final java.lang.String toString()
Default Edition of the Qbox value

Overrides:
toString in class java.lang.Object
Returns:
the string equivalent of the coocube the letter 'A' is appended for ANY IN QBOX.

list

public java.util.Enumeration list()
List in an enumeration all Qboxes corresponding to a qbox To get all qboxes, just do the following: cq = new Qbox(); e=cq.list();

Returns:
a list of Qboxes existing at the default level contained in the Object.

list

public static java.util.Enumeration list(java.util.ArrayList vector)
List in an enumeration all Qboxes selected in a ArrayList

Parameters:
vector - a ArrayList of qboxes returned from a select routine
Returns:
an Enumeration of leaf Qboxes.

list

public static java.util.Enumeration list(Region region)
Return all Qboxes concerned by a Region (circle, box, zone, etc...)

Parameters:
region - A region defined according to AbstractRegion.
Returns:
an Enumeration of leaf Qboxes.

circle

public static java.util.Enumeration circle(Coo center,
                                           double radius)

equals

public boolean equals(java.lang.Object o)
MOD-BB 21-01-04 Ajout de cette methode. Test d'egalite de QBox.

Overrides:
equals in class java.lang.Object
Parameters:
o - Object a comparer.
Returns:
Vrai si o est identique a this, faux sinon.