NAME

Astro::Nova - Perl interface to libnova

SYNOPSIS

use Astro::Nova qw(functions ...);
my $hms = Astro::Nova::HMS->new();
$hms->set_hours(12);
...

DESCRIPTION

A libnova wrapper that includes a copy of libnova 0.15.0 itself for static linking. See "COPYRIGHT AND LICENSE" for licensing details. The goal of this documentation is to document the Perl wrapper, not to reproduce the entire libnova documentation. Please find the documentation at http://libnova.sourceforge.net/.

In general, the available functions have the same name as the libnova functions, but with the ln_ prefix removed. That means ln_get_mean_sidereal_time(JD) becomes in Perl either Astro::Nova::get_mean_sidereal_time($jd) or if exported get_mean_sidereal_time($jd).

The functions' interfaces will be mostly the same as in C, except that the libnova structs are available as Perl classes. See "STRUCTS". If there are other changes to the interface, the changes will be documented in the list of exported functions below.

EXPORT

None by default.

Many functions can be exported on demand. They will be added to the list as they become available. The function list will look remotely like a C-level signature but refer to classes instead of C structs. Some of the interfaces have been changed to return a value instead of passing pointers as arguments. The ln_ prefix has been stripped.

abberation.h
  Astro::Nova::EquPosn get_equ_aber(Astro::Nova::EquPosn mean_position, double JD)
  Astro::Nova::LnLatPosn get_ecl_aber(Astro::Nova::LnLatPosn mean_position, double JD)

airmass.h
  double get_airmass(double alt, double airmass_scale)
  double get_alt_from_airmass(double X, double airmass_scale)

angular_separation.h
  double get_angular_separation(Astro::Nova::EquPosn posn1, Astro::Nova::EquPosn posn2)
  double get_rel_posn_angle(Astro::Nova::EquPosn posn1, Astro::Nova::EquPosn posn2)

apparent_position.h
  Astro::Nova::EquPosn get_apparent_posn(Astro::Nova::EquPosn mean_position,
                                         Astro::Nova::EquPosn proper_motion,
                                         double JD)

asteroid.h
  double get_asteroid_mag(double JD, Astro::Nova::EllOrbit orbit, double H, double G)
  double get_asteroid_sdiam_km(double H, double A)
  double get_asteroid_sdiam_arc(double JD, Astro::Nova::EllOrbit orbit, double H, double A)

comet.h
  double get_ell_comet_mag(double JD, Astro::Nova::EllOrbit orbit, double g, double k)
  double get_par_comet_mag(double JD, Astro::Nova::ParOrbit orbit, double g, double k)

dynamical_time.h
  double get_dynamical_time_diff(double JD)
  double get_jde(double JD)

sidereal_time.h
  double get_mean_sidereal_time(double JD)
  double get_apparent_sidereal_time(double JD)

earth.h
  Astro::Nova::HelioPosn get_earth_helio_coords(double JD)
  double get_earth_solar_dist(double JD)
  Astro::Nova::RectPosn get_earth_rect_helio(double JD)
  (double $p_sin_o, double $p_cos_o) = get_earth_centre_dist(float height, double latitude)

elliptic_motion.h
  double solve_kepler(double e, double M)
  double get_ell_mean_anomaly(double n, double delta_JD)
  double get_ell_true_anomaly(double e, double E)
  double get_ell_radius_vector(double a, double e, double E)
  double get_ell_smajor_diam(double e, double q)
  double get_ell_sminor_diam(double e, double a)
  double get_ell_mean_motion(double a)
  Astro::Nova::RectPosn get_ell_geo_rect_posn(Astro::Nova::EllOrbit orbit, double JD)
  Astro::Nova::RectPosn get_ell_helio_rect_posn(Astro::Nova::EllOrbit orbit, double JD)
  double get_ell_orbit_len(Astro::Nova::EllOrbit orbit)
  double get_ell_orbit_vel(double JD, Astro::Nova::EllOrbit orbit)
  double get_ell_orbit_pvel(Astro::Nova::EllOrbit orbit)
  double get_ell_orbit_avel(Astro::Nova::EllOrbit orbit)
  double get_ell_body_phase_angle(double JD, Astro::Nova::EllOrbit orbit)
  double get_ell_body_elong(double JD, Astro::Nova::EllOrbit orbit)
  double get_ell_body_solar_dist(double JD, Astro::Nova::EllOrbit orbit)
  double get_ell_body_earth_dist(double JD, Astro::Nova::EllOrbit orbit)
  Astro::Nova::EquPosn get_ell_body_equ_coords(double JD, Astro::Nova::EllOrbit orbit)
  (int $status, Astro::Nova::RstTime $rst) =
    get_ell_body_rst(double JD, Astro::Nova::LnLatPosn observer, Astro::Nova::EllOrbit orbit)
  (int $status, Astro::Nova::RstTime $rst) =
    get_ell_body_rst_horizon(double JD, Astro::Nova::LnLatPosn observer,
                             Astro::Nova::EllOrbit orbit, double horizon)
  (int $status, Astro::Nova::RstTime $rst) =
    get_ell_body_next_rst(double JD, Astro::Nova::LnLatPosn observer, Astro::Nova::EllOrbit orbit)
  (int $status, Astro::Nova::RstTime $rst) =
    get_ell_body_next_rst_horizon(double JD, Astro::Nova::LnLatPosn observer,
                                  Astro::Nova::EllOrbit orbit, double horizon)
  (int $status, Astro::Nova::RstTime $rst) =
    get_ell_body_next_rst_horizon_future(double JD, Astro::Nova::LnLatPosn observer,
                                         Astro::Nova::EllOrbit orbit, double horizon,
                                         int day_limit)
  double get_ell_last_perihelion(double epoch_JD, double M, double n)

heliocentric_time.h
  double get_heliocentric_time_diff(double JD, Astro::Nova::EquPosn object)

hyperbolic_motion.h
  double solve_hyp_barker(double Q1, double G, double t)
  double get_hyp_true_anomaly(double q, double e, double t)
  double get_hyp_radius_vector(double q, double e, double t)
  Astro::Nova::RectPosn get_hyp_geo_rect_posn(Astro::Nova::HypOrbit orbit, double JD)
  Astro::Nova::RectPosn get_hyp_helio_rect_posn(Astro::Nova::HypOrbit orbit, double JD)
  Astro::Nova::EquPosn get_hyp_body_equ_coords(double JD, Astro::Nova::HypOrbit orbit)
  double get_hyp_body_earth_dist(double JD, Astro::Nova::HypOrbit orbit)
  double get_hyp_body_solar_dist(double JD, Astro::Nova::HypOrbit orbit)
  double get_hyp_body_phase_angle(double JD, Astro::Nova::HypOrbit orbit)
  double get_hyp_body_elong(double JD, Astro::Nova::HypOrbit orbit)
  (int $status, Astro::Nova::RstTime $rst) =
    get_hyp_body_rst(double JD, Astro::Nova::LnLatPosn observer, Astro::Nova::HypOrbit orbit)
  (int $status, Astro::Nova::RstTime $rst) =
    get_hyp_body_rst_horizon(double JD, Astro::Nova::LnLatPosn observer,
                             Astro::Nova::HypOrbit orbit, double horizon)
  (int $status, Astro::Nova::RstTime $rst) =
    get_hyp_body_next_rst(double JD, Astro::Nova::LnLatPosn observer, Astro::Nova::HypOrbit orbit)
  (int $status, Astro::Nova::RstTime $rst) =
    get_hyp_body_next_rst_horizon(double JD, Astro::Nova::LnLatPosn observer,
                                  Astro::Nova::HypOrbit orbit, double horizon)
  (int $status, Astro::Nova::RstTime $rst) =
    get_hyp_body_next_rst_horizon_future(double JD, Astro::Nova::LnLatPosn observer,
                                         Astro::Nova::HypOrbit orbit, double horizon,
                                         int day_limit)

julian_day.h
  double get_julian_day(Astro::Nova::Date date)
  Astro::Nova::Date get_date(double JD)
  Astro::Nova::Date get_date_from_timet(time_t t) (time_t is an integer)
  Astro::Nova::ZoneDate get_local_date(double JD)
  unsigned int get_day_of_week(Astro::Nova::Date date)
  double get_julian_from_sys()
  Astro::Nova::Date get_date_from_sys()
  double get_julian_from_timet(time_t t) (time_t is an integer)
  time_t get_timet_from_julian(double JD) (time_t is an integer)
  double get_julian_local_date(Astro::Nova::ZoneDate zonedate)
  Astro::Nova::ZoneDate date_to_zonedate(Astro::Nova::Date date, long gmtoff)
  Astro::Nova::Date zonedate_to_date(Astro::Nova::ZoneDate zonedate)

jupiter.h
  double get_jupiter_equ_sdiam(double JD)
  double get_jupiter_pol_sdiam(double JD)
  Astro::Nova::RstTime get_jupiter_rst(double JD)
  Astro::Nova::HelioPosn get_jupiter_helio_coords(double JD)
  Astro::Nova::EquPosn get_jupiter_equ_coords(double JD)
  double get_jupiter_earth_dist(double JD)
  double get_jupiter_solar_dist(double JD)
  double get_jupiter_magnitude(double JD)
  double get_jupiter_disk(double JD)
  double get_jupiter_phase(double JD)
  Astro::Nova::RectPosn get_jupiter_rect_helio(double JD)

lunar.h
  double get_lunar_sdiam(double JD)
  Astro::Nova::RstTime get_lunar_rst(double JD, Astro::Nova::LnLatPosn observer)
  Astro::Nova::RectPosn get_lunar_geo_posn(double JD, double precision)
  Astro::Nova::EquPosn get_lunar_equ_coords_prec(double JD, double precision)
  Astro::Nova::EquPosn get_lunar_equ_coords(double JD)
  Astro::Nova::LnLatPosn get_lunar_ecl_coords(double JD, double precision)
  double get_lunar_phase(double JD)
  double get_lunar_disk(double JD)
  double get_lunar_earth_dist(double JD)
  double get_lunar_bright_limb(double JD)
  double get_lunar_long_asc_node(double JD)
  double get_lunar_long_perigee(double JD)

mars.h
  double get_mars_sdiam(double JD)
  Astro::Nova::RstTime get_mars_rst(double JD)
  Astro::Nova::HelioPosn get_mars_helio_coords(double JD)
  Astro::Nova::EquPosn get_mars_equ_coords(double JD)
  double get_mars_earth_dist(double JD)
  double get_mars_solar_dist(double JD)
  double get_mars_magnitude(double JD)
  double get_mars_disk(double JD)
  double get_mars_phase(double JD)
  Astro::Nova::RectPosn get_mars_rect_helio(double JD)

mercury.h
neptune.h
uranus.h
venus.h
  Same as mars, except the planet name is replaced in the method names.

nutation.h
  Astro::Nova::Nutation get_nutation(double JD)

parabolic_motion.h
  double solve_barker(double q, double t)
  double get_par_true_anomaly(double q, double t)
  double get_par_radius_vector(double q, double t)
  Astro::Nova::RectPosn get_par_geo_rect_posn(Astro::Nova::ParOrbit orbit, double JD)
  Astro::Nova::RectPosn get_par_helio_rect_posn(Astro::Nova::ParOrbit orbit, double JD)
  Astro::Nova::EquPosn get_par_body_equ_coords(double JD, Astro::Nova::ParOrbit orbit)
  double get_par_body_earth_dist(double JD, Astro::Nova::ParOrbit orbit)
  double get_par_body_solar_dist(double JD, Astro::Nova::ParOrbit orbit)
  double get_par_body_phase_angle(double JD, Astro::Nova::ParOrbit orbit)
  double get_par_body_elong(double JD, Astro::Nova::ParOrbit orbit)
  (int $status, Astro::Nova::RstTime $rst) =
    get_par_body_rst(double JD, Astro::Nova::LnLatPosn observer)
  (int $status, Astro::Nova::RstTime $rst) =
    get_par_body_rst_horizon(double JD, Astro::Nova::LnLatPosn observer, double horizon)
  (int $status, Astro::Nova::RstTime $rst) =
    get_par_body_next_rst(double JD, Astro::Nova::LnLatPosn observer)
  (int $status, Astro::Nova::RstTime $rst) =
    get_par_body_next_rst_horizon(double JD, Astro::Nova::LnLatPosn observer, double horizon)
  (int $status, Astro::Nova::RstTime $rst) =
    get_par_body_next_rst_horizon_future(double JD, Astro::Nova::LnLatPosn observer,
                                         double horizon, int day_limit)

parallax.h
  Astro::Nova::EquPosn get_parallax(Astro::Nova::EquPosn object, double au_distance,
                                    Astro::Nova::LnLatPosn observer, double height, double JD)
  Astro::Nova::EquPosn get_parallax_ha(Astro::Nova::EquPosn object, double au_distance,
                                       Astro::Nova::LnLatPosn observer, double height, double H)

precession.h
  Astro::Nova::EquPosn get_equ_prec(Astro::Nova::EquPosn mean_position, double JD)
  Astro::Nova::EquPosn get_equ_prec2(Astro::Nova::EquPosn mean_position, double fromJD, double toJD)
  Astro::Nova::LnLatPosn get_ecl_prec(Astro::Nova::LnLatPosn mean_position, double JD)

proper_motion.h
  Astro::Nova::EquPosn get_equ_pm(Astro::Nova::EquPosn mean_position,
                                  Astro::Nova::EquPosn proper_motion, double JD)
  Astro::Nova::EquPosn get_equ_pm(Astro::Nova::EquPosn mean_position,
                                  Astro::Nova::EquPosn proper_motion, double JD, double epoch_JD)

refraction.h
  double get_refraction_adj(double altitude, double atm_pres, double temp)

rise_set.h
  (int $status, Astro::Nova::RstTime $rst) =
    get_object_rst(double JD, Astro::Nova::LnLatPosn observer, Astro::Nova::EquPosn object)
  (int $status, Astro::Nova::RstTime $rst) =
    get_object_rst_horizon(double JD, Astro::Nova::LnLatPosn observer,
                           Astro::Nova::EquPosn object, double horizon)
  (int $status, Astro::Nova::RstTime $rst) =
    get_object_next_rst(double JD, Astro::Nova::LnLatPosn observer, Astro::Nova::EquPosn object)
  (int $status, Astro::Nova::RstTime $rst) =
    get_object_next_rst_horizon(double JD, Astro::Nova::LnLatPosn observer,
                                Astro::Nova::EquPosn object, double horizon)

saturn.h
  Same as jupiter, except the planet name is replaced in the method names.

solar.h
  (int $status, Astro::Nova::RstTime $rst) =
    get_solar_rst(double JD, Astro::Nova::LnLatPosn observer)
  (int $status, Astro::Nova::RstTime $rst) =
    get_solar_rst_horizon(double JD, Astro::Nova::LnLatPosn observer, double horizon)
  Astro::Nova::HelioPosn get_solar_geom_coords(double JD)
  Astro::Nova::EquPosn get_solar_equ_coords(double JD)
  Astro::Nova::LnLatPosn get_solar_ecl_coords(double JD)
  Astro::Nova::RectPosn get_solar_geo_coords(double JD)
  double get_solar_sdiam(double JD)

transform.h
  Astro::Nova::HrzPosn get_hrz_from_equ(Astro::Nova::EquPosn object, Astro::Nova::LnLatPosn observer, double JD)
  Astro::Nova::HrzPosn get_hrz_from_equ_sidereal_time(Astro::Nova::EquPosn object, Astro::Nova::LnLatPosn observer, double sidereal)
  Astro::Nova::EquPosn get_equ_from_ecl(Astro::Nova::LnLatPosn object, double JD)
  Astro::Nova::LnLatPosn get_ecl_from_equ(Astro::Nova::EquPosn object, double JD)
  Astro::Nova::EquPosn get_equ_from_hrz(Astro::Nova::HrzPosn object, Astro::Nova::LnLatPosn observer, double JD)
  Astro::Nova::RectPosn get_rect_from_helio(Astro::Nova::HelioPosn helio)
  Astro::Nova::LnLatPosn get_ecl_from_rect(Astro::Nova::RectPosn rect)
  Astro::Nova::EquPosn get_equ_from_gal(Astro::Nova::GalPosn gal)
  Astro::Nova::EquPosn get_equ2000_from_gal(Astro::Nova::GalPosn gal)
  Astro::Nova::GalPosn get_gal_from_equ(Astro::Nova::EquPosn equ)
  Astro::Nova::GalPosn get_gal_from_equ2000(Astro::Nova::EquPosn equ)

utility.h
  const char* get_version()
  double get_dec_location(char* s)
  const char* get_humanr_location(double location)
  double get_rect_distance(Astro::Nova::RectPosn a, Astro::Nova::RectPosn b)
  double rad_to_deg(double radians)
  double deg_to_rad(double degrees)
  double hms_to_deg(Astro::Nova::HMS hms)
  Astro::Nova::HMS deg_to_hms(double degrees)
  double hms_to_rad(Astro::Nova::HMS hms)
  Astro::Nova::HMS rad_to_hms(double radians)
  double dms_to_deg(Astro::Nova::DMS dms)
  Astro::Nova::DMS deg_to_dms(double degrees)
  double dms_to_rad(Astro::Nova::DMS dms)
  Astro::Nova::DMS rad_to_dms(double radians)
  Astro::Nova::EquPosn hequ_to_equ(Astro::Nova::HEquPosn hpos)
  Astro::Nova::HEquPosn equ_to_hequ(Astro::Nova::EquPosn pos)
  Astro::Nova::HrzPosn hhrz_to_hrz(Astro::Nova::HHrzPosn hpos)
  Astro::Nova::HHrzPosn hrz_to_hhrz(Astro::Nova::HrzPosn pos)
  Astro::Nova::LnLatPosn hlnlat_to_lnlat(Astro::Nova::HLnLatPosn hpos)
  Astro::Nova::HLnLatPosn lnlat_to_hlnlat(Astro::Nova::hLnLatPosn pos)
  void add_secs_hms(Astro::Nova::HMS hms, double seconds)
  void add_hms(Astro::Nova::HMS source, Astro::Nova::HMS dest)
  double get_light_time(double dist)

STRUCTS / CLASSES

libnova defines several structs for passing data to or receiving results from the functions. These have been wrapped as Perl classes. Below is a list of the struct names, their Perl class names, and their data members (including the C types). The class constructors optionally take key/value pairs as argument that correspond to the struct members. Any extra parameters that aren't struct members are currently simply ignored. Any struct members that aren't explicitly set will be set to zero.

If a member is called L, then there will be two methods get_L and set_L for getting/setting the data. All numeric data is intialized to zero.

ln_date

Implemented as Astro::Nova::Date.

int years
int months
int days
int hours
int minutes
double seconds

ln_dms

Implemented as Astro::Nova::DMS.

unsigned short  neg
unsigned short  degrees
unsigned short  minutes
double  seconds

ln_ell_orbit

Implemented as Astro::Nova::EllOrbit.

double  a
double  e
double  i
double  w
double  omega
double  n
double  JD

ln_equ_posn

Implemented as Astro::Nova::EquPosn.

double  ra
double  dec

ln_gal_posn

Implemented as Astro::Nova::GalPosn.

double  l
double  b

ln_helio_posn

Implemented as Astro::Nova::HelioPosn.

double  L
double  B
double  R

ln_hms

Implemented as Astro::Nova::HMS.

unsigned short  hours
unsigned short  minutes
double  seconds

ln_hrz_posn

Implemented as Astro::Nova::HrzPosn.

double  az
double  alt

ln_hyp_orbit

Implemented as Astro::Nova::HypOrbit.

double  q
double  e
double  i
double  w
double  omega
double  JD

ln_lnlat_posn

Implemented as Astro::Nova::LnLatPosn.

double  lng
double  lat

ln_nutation

Implemented as Astro::Nova::Nutation.

double  longitude
double  obliquity
double  ecliptic

ln_par_orbit

Implemented as Astro::Nova::ParOrbit.

double  q
double  i
double  w
double  omega
double  JD

ln_rect_posn

Implemented as Astro::Nova::RectPosn.

double  X
double  Y
double  Z

ln_rst_time

Implemented as Astro::Nova::RstTime.

double  rise
double  set
double  transit

ln_zonedate

Implemented as Astro::Nova::ZoneDate.

int  years
int  months
int  days
int  hours
int  minutes
double  seconds
long  gmtoff

These are "human readable" composite structs that contain others. Accessing their memebers with a getter method will return a new copy of the contained structure.

lnh_equ_posn

Implemented as Astro::Nova::HEquPosn.

struct ln_hms ra
struct ln_dms dec

lnh_hrz_posn

Implemented as Astro::Nova::HHrzPosn.

struct ln_dms az
struct ln_dms alt

lnh_lnlat_posn

Implemented as Astro::Nova::HLnLatPosn.

struct ln_dms lng
struct ln_dms lat

AUTHOR

Steffen Mueller, <smueller@cpan.org>

COPYRIGHT AND LICENSE

The wrapper code is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.0 or, at your option, any later version of Perl 5 you may have available.

libnova is maintained by Liam Girdwood and Petr Kubanek.

libnova is released under the GNU LGPL. This may limit the licensing terms of the wrapper code. If in doubt, ask a lawyer.

To install Astro::Nova, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Astro::Nova

CPAN shell

perl -MCPAN -e shell
install Astro::Nova

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)