org.jscience.astronomy
Class MiscellaneousUtils

java.lang.Object
  extended by org.jscience.astronomy.MiscellaneousUtils

public final class MiscellaneousUtils
extends java.lang.Object

MiscellaneousUtils is a loose collection of methods for all sorts of general little tasks, such as mathematics, string stuff, line i/o etc. It also collects some constants we need in a variety of classes, similar to Java's Math.E and Math.PI, although this would normally be the task of the common base class of the classes that need a constant.

Copyright: © 2002-2004 Horst Meyerdierks.

This programme is free software; you can redistribute it and/or modify it under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version.

This programme is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.

You should have received a copy of the GNU General Public Licence along with this programme; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

$Id: MiscellaneousUtils.java,v 1.2 2007/10/21 17:43:14 virtualcall Exp $

2.7: 2004/02/03 hme
Added WTime6.
2.6: 2004/02/02 hme
Added WTime5.
2.5: 2003/09/18 hme
Fix bug in WTime4 whereby it would always write the minute with on decimal (which was always .0 as it should be).
2.4: 2003/09/16 hme
Package review. Renamed from SputnikLib to MiscellaneousUtils.
2.2: 2003/09/15 hme
Change date format from Y/M/D- to Y-M-D-.
1.16: 2002/07/16 hme
RTime3 now throws an exception if the year or month are not integer. Before it would return their integer value instead. Also improved handling of mantissa/exponent numbers in Rfndm, in particular less chance of a crash due to invalid input.
1.14: 2002/07/14 hme
Consolidating documentation. Also enhance Rrndm() to read mantissa/exponent numbers.
1.13: 2002/07/13 hme
Fix format for Rfndm so that commas are not taken as part of a number but as separators. Add SpherDist().
1.12: 2002/07/07 hme
Add support for precision 1 to Wfndm.
1.11: 2002/06/23 hme
Add NormAngle0() and NormAngle180().
1.10: 2002/06/22 hme
Add SpherAng().
1.9: 2002/06/22 hme
Add Rect().
1.8: 2002/06/17 hme
Add Wdms() and Wfexp().
1.7: 2002/06/15 hme
Add support for precision 0 to Wfndm. Add Rstring() and Sstring(). Add Spher().
1.3: 2002/06/09 hme
Translated from C++ after Times class was finalised in the prospective version 2 of Sputnik.


Field Summary
static double DEGREES_PER_RADIAN
          Degrees per radian.
 
Constructor Summary
MiscellaneousUtils()
           
 
Method Summary
static double[] convertOrthogonalToSpherical(double[] aRect)
          Convert orthogonal to spherical coordinates.
static double[] convertSphericalToOrthogonal(double[] aSpher)
          Convert spherical to orthogonal coordinates.
static double[] degreesTodms(double aTime)
          Convert a number into a sexagesimal triplet.
static java.lang.String deQuoteString(java.lang.String aString)
          Read a string.
static double getSphericalAngle(double[] Triplets)
          Calculate a spherical angle.
static double normalizeAngleAt0(double aAngle)
          Normalise an angle around zero.
static double normalizeAngleAt180(double aAngle)
          Normalise an angle around 180°.
static void readDate(java.lang.String aString, int[] date, double[] time)
          Read date as year, month and day, time as hours, minutes and seconds.
static double readFloat(java.lang.String aString)
          Read a floating point number.
static double sphericalDistance(double[] aTriplet1, double[] aTriplet2)
          Calculate a spherical distance.
static java.lang.String stringRemainder(java.lang.String aString)
          Skip a string.
static void writeAngle(java.io.PrintStream stream, double degree)
          Write angle as degrees, arc minutes and arc seconds.
static void writeDate(java.io.PrintStream stream, double year, double month, double day)
          Write date as year, month and day.
static void writeExtendedDate(java.io.PrintStream stream, double year, double month, double day, double hour, double min, double sec)
          Write date as year, month and day, time as hours, minutes and seconds.
static void writeExtendedTime(java.io.PrintStream stream, double hour, double min, double sec)
          Write time as hours, minutes and seconds.
static void writeFloat(java.io.PrintStream aStream, double aNum)
          Write a number in 1.234E12 format.
static void writeFloat(java.io.PrintStream aStream, int aWidth, int aPrec, double aNum)
          Write a number to a fixed-width field.
static void writeRoundedDate(java.io.PrintStream stream, double year, double month, double day, double hour, double min, double sec)
          Write date as year, month and day, time as hours and minutes.
static void writeRoundedTime(java.io.PrintStream stream, double hour, double min, double sec)
          Write time as hours and minutes.
static void writeTime(java.io.PrintStream stream, double hour, double min, double sec)
          Write time as hours, minutes and seconds.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEGREES_PER_RADIAN

public static final double DEGREES_PER_RADIAN
Degrees per radian.

See Also:
Constant Field Values
Constructor Detail

MiscellaneousUtils

public MiscellaneousUtils()
Method Detail

degreesTodms

public static final double[] degreesTodms(double aTime)
Convert a number into a sexagesimal triplet.

The given number (e.g. an angle in degrees or a time in hours) is split into a triplet of numbers (degrees, arcmin, arcsec or hours, minutes, seconds).

Parameters:
aTime - Time or angle in hours or degrees.
Returns:
The triplet of hours, minutes, seconds or °, ', ".

normalizeAngleAt0

public static final double normalizeAngleAt0(double aAngle)
Normalise an angle around zero.

This normalises an angle in case it is outside the interval [-π,+π]. The returned value represents the same angle but is within this interval.

Parameters:
aAngle - The angle before normalisation.

normalizeAngleAt180

public static final double normalizeAngleAt180(double aAngle)
Normalise an angle around 180°.

This normalises an angle in case it is outside the interval [0,2π]. The returned value represents the same angle but is within this interval.

Parameters:
aAngle - The angle before normalisation.

convertSphericalToOrthogonal

public static final double[] convertSphericalToOrthogonal(double[] aSpher)
Convert spherical to orthogonal coordinates.

Take the given a,b,r coordinates and convert them to x,y,z where a is the azimuth angle in the x-y plane, b the elevation over the x-y plane, and r the distance from the origin. a and b are in radian, r in the same units as x, y and z.

Parameters:
aSpher - Triplet of spherical coordinates a, b, r.
Returns:
Triplet of rectangular coordinates x, y, z.

readFloat

public static final double readFloat(java.lang.String aString)
                              throws java.lang.Exception
Read a floating point number.

Given a string this trims off any leading and trailing white space and reads a floating point number from the start of the string. If the parsing fails an exception is thrown. The given string can be a plain number like 1234.5678 or one that is split into mantissa and exponent like 1.2345678E3. Mantissa or exponent can have a minus sign or indeed a plus sign in front of them. (This would be a trivial statement if this were written in C, but in Java this takes some coding to achieve.)

Parameters:
aString - The string to read from.
Throws:
java.lang.Exception

deQuoteString

public static final java.lang.String deQuoteString(java.lang.String aString)
Read a string.

Given a string this trims off any leading and trailing white space and reads a string from the start. The string read is usually a single word. But if the string begins with a double quote (") then the string read is all words between this and the matching closing quote. The quotes are sripped off. This routine will not recognise escaped quotes as part of the string, but as end of the string.

Parameters:
aString - The string to read from.

readDate

public static final void readDate(java.lang.String aString,
                                  int[] date,
                                  double[] time)
                           throws java.lang.Exception
Read date as year, month and day, time as hours, minutes and seconds.

Given a string of the form 2002-12-13-12:34:56.7, this routine returns the six numbers. The third number in the string can also be floating point. In that case its fractional part is added to the hours in order that all three date numbers can be returned as integers. All numbers can be negative (inlcuding the hours, which are given behind a - character). Each negative sign affects only the one number. The given string will be trimmed for leading and trailing blanks before reading. But the separators between the numbers must be precisely as shown, i.e. single characters -,-,-,:,:. If this is not the case an exception is thrown.

Parameters:
aString - The string to read from.
date - The triplet of integers that are year, month and day.
time - The triplet of floating point numbers that are hours, minutes and seconds.
Throws:
java.lang.Exception

convertOrthogonalToSpherical

public static final double[] convertOrthogonalToSpherical(double[] aRect)
Convert orthogonal to spherical coordinates.

Take the given x,y,z coordinates and convert them to a,b,r where a is the azimuth angle in the x-y plane, b the elevation over the x-y plane, and r the distance from the origin. a and b are in radian, r in the same units as x, y and z.

Parameters:
aRect - Triplet of rectangular coordinates x, y, z.
Returns:
Triplet of spherical coordinates a, b, r.

getSphericalAngle

public static final double getSphericalAngle(double[] Triplets)
Calculate a spherical angle.

The three given xyz triplets define a spherical triangle on the unit sphere. The returned value is the angle at the second corner. To calculate a postition angle, give the North Pole {0,0,1} as the first position, the bright component or reference positions as second and the faint component as third. To calculate the parallactic angle give the zenith {0,0,1} as first, the position of interest Rect({A,h,1}) as second and the North Celestial Pole Rect({0,φ,1}) as third.

Parameters:
Triplets - Nine numbers x1, y1, z1, x2, y2, z2, x3, y3, z3. Each group of three is a vector that defines one corner of the spherical triangle.

sphericalDistance

public static final double sphericalDistance(double[] aTriplet1,
                                             double[] aTriplet2)
Calculate a spherical distance.

The given xyz triplets define two directions. The returned value is the angle between the two vectors. In the first instance the distance is calculated as the arccos of the dot product of the two unit vectors. If this results in a distance less than ~1° or more than ~179°, then the distance is recalculated as the arcsin of the cross product.

Parameters:
aTriplet1 - The first vector.
aTriplet2 - The second vector.

stringRemainder

public static final java.lang.String stringRemainder(java.lang.String aString)
Skip a string.

Given a string this behaves like deQuoteString, but returns the remainder of the given string instead of the string read.

Parameters:
aString - The string to read from.

writeAngle

public static final void writeAngle(java.io.PrintStream stream,
                                    double degree)
Write angle as degrees, arc minutes and arc seconds.

Format the given triplet of in the form " 12:34:56" or "-12:34:56". Note the leading blank for positive angles.

Parameters:
stream - The stream to write to.
degree - The angle in degrees.

writeFloat

public static final void writeFloat(java.io.PrintStream aStream,
                                    double aNum)
Write a number in 1.234E12 format.

Format the given floating point number into a string of lenth 8 with 4 significant digits, 3 of them behind the decimal dot.

Parameters:
aStream - The stream to write to.
aNum - The number to format and write.

writeFloat

public static final void writeFloat(java.io.PrintStream aStream,
                                    int aWidth,
                                    int aPrec,
                                    double aNum)
Write a number to a fixed-width field.

Format the given floating point number into a string of fixed lenth with the number on its right (blank-padded on the left). The given field width can have any positive integer value. If it is too small to fit the number a longer string is generated. The precision can currently be given as 0, 1, 3, 6 or 9 digits behind the decimal point. If another precision is given, 3 is used anyway. As an example the number -1234.567 with a width of 14 and a precision of 6 should come out as "  -1234.567000".

Parameters:
aStream - The stream to write to.
aWidth - The number of characters to write.
aPrec - The number of digits behind the decimal point.
aNum - The number to format and write.

writeRoundedTime

public static final void writeRoundedTime(java.io.PrintStream stream,
                                          double hour,
                                          double min,
                                          double sec)
Write time as hours and minutes.

Round and format the given triplet of hour, minute and second into hours and minutes of the form 12:35 where the second number takes into account the third. The rounding is also modified to prevent the second number to reach the value 60 on output.

Parameters:
stream - The stream to write to.
hour - First sexagesimal unit, hour or °.
min - Second sexagesimal unit, minute or '.
sec - Third sexagesimal unit, second or ".

writeExtendedTime

public static final void writeExtendedTime(java.io.PrintStream stream,
                                           double hour,
                                           double min,
                                           double sec)
Write time as hours, minutes and seconds.

Format the given triplet of hour, minute and second in the form 12:34:56.7.

Parameters:
stream - The stream to write to.
hour - First sexagesimal unit, hour or °.
min - Second sexagesimal unit, minute or '.
sec - Third sexagesimal unit, second or ".

writeExtendedDate

public static final void writeExtendedDate(java.io.PrintStream stream,
                                           double year,
                                           double month,
                                           double day,
                                           double hour,
                                           double min,
                                           double sec)
Write date as year, month and day, time as hours, minutes and seconds.

Format the given sextuplet of year, month, day, hour, minute and second in the form 2002-12-13-12:34:56.7.

Parameters:
stream - The stream to write to.
year - Year.
month - Month.
day - Day.
hour - Hour.
min - Minute.
sec - Second.

writeRoundedDate

public static final void writeRoundedDate(java.io.PrintStream stream,
                                          double year,
                                          double month,
                                          double day,
                                          double hour,
                                          double min,
                                          double sec)
Write date as year, month and day, time as hours and minutes.

Format the given sextuplet of year, month, day, hour, minute and second in the form 2002-12-13-12:35 where the fifth number takes into account the sixth. The rounding is also modified to prevent the fifth number to reach the value 60 on output.

Parameters:
stream - The stream to write to.
year - Year.
month - Month.
day - Day.
hour - Hour.
min - Minute.
sec - Second.

writeDate

public static final void writeDate(java.io.PrintStream stream,
                                   double year,
                                   double month,
                                   double day)
Write date as year, month and day.

Format the given triplet of year, month and day in the form 2002-12-13.

Parameters:
stream - The stream to write to.
year - Year.
month - Month.
day - Day.

writeTime

public static final void writeTime(java.io.PrintStream stream,
                                   double hour,
                                   double min,
                                   double sec)
Write time as hours, minutes and seconds.

Format the given triplet of hour, minute and second in the form 12:34:56.

Parameters:
stream - The stream to write to.
hour - First sexagesimal unit, hour or °.
min - Second sexagesimal unit, minute or '.
sec - Third sexagesimal unit, second or ".