Observing frames

Data Structures
struct	novas_frame
	A set of parameters that uniquely define the place and time of observation. More...
struct	novas_matrix
	A 3x3 matrix for coordinate transformations. More...
struct	novas_transform
	A transformation between two astronomical coordinate systems for the same observer location and time. More...
struct	sky_pos
	Celestial object's place on the sky; contains the output from place() More...

Macros
#define	NOVAS_FRAME_INIT
	Empty initializer for novas_frame.
#define	NOVAS_TRANSFORM_INIT
	Empty initializer for NOVAS_TRANSFORM.

Enumerations
enum	novas_accuracy { NOVAS_FULL_ACCURACY = 0 , NOVAS_REDUCED_ACCURACY }
	Constants to control the precision of NOVAS nutation calculations. More...

Functions
int	novas_change_observer (const novas_frame *orig, const observer *obs, novas_frame *out)
	Change the observer location for an observing frame.
int	novas_invert_transform (const novas_transform *transform, novas_transform *inverse)
	Inverts a novas coordinate transformation matrix.
int	novas_make_frame (enum novas_accuracy accuracy, const observer *obs, const novas_timespec *time, double xp, double yp, novas_frame *frame)
	Sets up a observing frame for a specific observer location, time of observation, and accuracy requirement.
int	novas_make_transform (const novas_frame *frame, enum novas_reference_system from_system, enum novas_reference_system to_system, novas_transform *transform)
	Calculates a transformation matrix that can be used to convert positions and velocities from one coordinate reference system to another.

Detailed Description

Macro Definition Documentation

NOVAS_FRAME_INIT

#define NOVAS_FRAME_INIT

Empty initializer for novas_frame.

Since

1.3

See also

novas_frame

NOVAS_TRANSFORM_INIT

#define NOVAS_TRANSFORM_INIT

Empty initializer for NOVAS_TRANSFORM.

Since

1.3

See also

novas_transform

Enumeration Type Documentation

novas_accuracy

enum novas_accuracy

Constants to control the precision of NOVAS nutation calculations.

See also

novas_make_frame()

Enumerator
NOVAS_FULL_ACCURACY	Use full precision calculations to micro-arcsecond accuracy. It can be computationally intensive when using the dynamical equator.
NOVAS_REDUCED_ACCURACY	Calculate with truncated terms. It can be significantly faster if a few milliarcsecond accuracy is sufficient.

Function Documentation

novas_change_observer()

int novas_change_observer	(	const novas_frame *	orig,
		const observer *	obs,
		novas_frame *	out )

Change the observer location for an observing frame.

Parameters

	orig	Pointer to original observing frame
	obs	New observer location
[out]	out	Observing frame to populate with a original frame data and new observer location. It can be the same as the input.

Returns

0 if successfule or else an an error code from geo_posvel() (errno will also indicate the type of error).

Since

1.1

Author

Attila Kovacs

See also

novas_make_frame()

References novas_frame::accuracy, grav_bodies_full_accuracy, grav_bodies_reduced_accuracy, NOVAS_FULL_ACCURACY, novas_get_time(), NOVAS_TDB, obs_planets(), novas_frame::obs_pos, novas_frame::observer, novas_frame::planets, novas_frame::state, and novas_frame::time.

novas_invert_transform()

int novas_invert_transform	(	const novas_transform *	transform,
		novas_transform *	inverse )

Inverts a novas coordinate transformation matrix.

Parameters

	transform	Pointer to a coordinate transformation matrix.
[out]	inverse	Pointer to a coordinate transformation matrix to populate with the inverse transform. It may be the same as the input.

Returns

0 if successful, or else -1 if the was an error (errno will indicate the type of error).

Since

1.1

Author

Attila Kovacs

See also

novas_make_transform()

References novas_transform::matrix.

novas_make_frame()

int novas_make_frame	(	enum novas_accuracy	accuracy,
		const observer *	obs,
		const novas_timespec *	time,
		double	xp,
		double	yp,
		novas_frame *	frame )

Sets up a observing frame for a specific observer location, time of observation, and accuracy requirement.

The frame is initialized using the currently configured planet ephemeris provider function (see set_planet_provider() and set_planet_provider_hp()), and in case of reduced accuracy mode, the currently configured IAU nutation model provider (see set_nutation_lp_provider()).

Note, that to construct full accuracy frames, you will need a high-precision ephemeris provider for the major planets (not just the default Earth/Sun), as without it, gravitational bending around massive plannets cannot be accounted for, and therefore μas accuracy cannot be ensured, in general. Attempting to construct a high-accuracy frame without a high-precision ephemeris provider for the major planets will result in an error in the 10–40 range from the required ephemeris() call.

NOTES:

1. This function expects the Earth polar wobble parameters to be defined on a per-frame basis and will not use the legacy global (undated) orientation parameters set via cel_pole().
2. The Earth orientation parameters xp, yp should be provided in the same ITRF realization as the observer location for an Earth-based observer. You can use novas_itrf_transform_eop() to convert the EOP values as necessary.

Parameters

	accuracy	Accuracy requirement, NOVAS_FULL_ACCURACY (0) for the utmost precision or NOVAS_REDUCED_ACCURACY (1) if ~1 mas accuracy is sufficient.
	obs	Observer location
	time	Time of observation
	xp	[mas] Earth orientation parameter, polar offset in x, e.g. from the IERS Bulletins, and possibly corrected for diurnal and semi-diurnal variations, e.g. via novas_diurnal_eop(). (The global, undated value set by cel_pole() is not not used here.) You can use 0.0 if sub-arcsecond accuracy is not required.
	yp	[mas] Earth orientation parameter, polar offset in y, e.g. from the IERS Bulletins, and possibly corrected for diurnal and semi-diurnal variations, e.g. via novas_diurnal_eop(). (The global, undated value set by cel_pole() is not not used here.) You can use 0.0 if sub-arcsecond accuracy is not required.
[out]	frame	Pointer to the observing frame to configure.

Returns

0 if successful, 10–40: error is 10 + the error from ephemeris(), 40–50: error is 40 + the error from geo_posvel(), or else -1 if there was an error (errno will indicate the type of error).

Since

1.1

Author

Attila Kovacs

See also

novas_change_observer(), novas_sky_pos(), novas_geom_posvel(), novas_make_transform()

set_planet_provider(), set_planet_provider_hp(), set_nutation_lp_provider(), novas_diurnal_eop(), novas_itrf_transform_eop()

References novas_frame::accuracy, novas_frame::deps0, novas_frame::dpsi0, novas_frame::dx, novas_frame::dy, novas_frame::earth_pos, novas_frame::earth_vel, novas_frame::ee, ephemeris(), era(), novas_frame::era, novas_timespec::fjd_tt, novas_frame::gst, novas_timespec::ijd_tt, mean_obliq(), novas_frame::mobl, NOVAS_BARYCENTER, novas_change_observer(), NOVAS_EARTH_INIT, novas_get_split_time(), NOVAS_JD_J2000, NOVAS_OBSERVER_PLACES, NOVAS_REDUCED_ACCURACY, NOVAS_SUN_INIT, NOVAS_UT1, nutation_angles(), novas_frame::state, novas_frame::sun_pos, novas_frame::sun_vel, novas_frame::time, novas_frame::tobl, tt2tdb(), and observer::where.

novas_make_transform()

int novas_make_transform	(	const novas_frame *	frame,
		enum novas_reference_system	from_system,
		enum novas_reference_system	to_system,
		novas_transform *	transform )

Calculates a transformation matrix that can be used to convert positions and velocities from one coordinate reference system to another.

Parameters

	frame	Observer frame, defining the location and time of observation
	from_system	Original coordinate reference system
	to_system	New coordinate reference system
[out]	transform	Pointer to the transform data structure to populate.

Returns

0 if successful, or else -1 if there was an error (errno will indicate the type of error).

Since

1.1

Author

Attila Kovacs

See also

novas_transform_vector(), novas_transform_sky_pos(), novas_invert_transform()

novas_geom_posvel(), novas_app_to_geom()

References novas_frame::era, novas_transform::frame, novas_transform::from_system, novas_frame::gcrs_to_cirs, novas_frame::icrs_to_j2000, novas_matrix::M, novas_transform::matrix, NOVAS_CIRS, NOVAS_GCRS, NOVAS_ICRS, NOVAS_ITRS, NOVAS_J2000, NOVAS_MOD, NOVAS_REFERENCE_SYSTEMS, NOVAS_TIRS, NOVAS_TOD, novas_frame::nutation, novas_frame::precession, and novas_transform::to_system.