Observing frames

Observing frames are a combination of an observer place, and an specific time of observation. More...

Classes
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...

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

Typedefs
typedef struct novas_frame	novas_frame
	A set of parameters that uniquely define the place and time of observation.
typedef struct novas_matrix	novas_matrix
	A 3x3 matrix for coordinate transformations.
typedef struct novas_transform	novas_transform
	A transformation between two astronomical coordinate systems for the same observer location and time.

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

Observing frames are a combination of an observer place, and an specific time of observation.

SuperNOVAS observing frames are not to be confused with coordinate reference frames, even if the two do have aspects in common. Here, a frame provides a topological snapshot of apparent places of all sources on the sky, as well as their geometric locations and velocities in 3D space – without imposing a particular coordinate system on them. So, while a coordinate reference frame (such as ICRF) implies a particular choice of a coordinate system, a SuperNOVAS observing frame is essentially coordinate-system independent in nature.

The power of observing frames is that they make it easy to express locations on the celestial sphere in any coordinate system, and allow to convert apparent places and geometric coordinates between different coordinate systems with superior efficiency.

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

Typedef Documentation

novas_frame

typedef struct novas_frame novas_frame

A set of parameters that uniquely define the place and time of observation.

The user may initialize the frame with novas_make_frame(). Once the observer frame is set up, it can be used repeatedly to perform efficient calculations of multiple objects in the coordinate system of choice, much faster than what place() can do. Frames also allow for transforming coordinates calculated for one coordinate syste, into another coordinate system with little effort.

You should never set or change fields in this structure manually. Instead the structure should always be initialized by an appropriate call to novas_make_frame(). After that you may change the observer location, if need be, with novas_change_observer().

The structure may expand with additional field in the future. Thus neither its size nor its particular layout should be assumed fixed over SuperNOVAS releases.

Since

1.1

See also

novas_make_frame(), novas_change_observer(), novas_make_transform(), NOVAS_FRAME_INIT

novas_sky_pos(), novas_geom_posvel(), novas_geom_to_app(), novas_app_to_geom(), novas_app_to_hor(), novas_hor_to_app(), novas_rises_above(), novas_sets_below(), novas_transit_time()

novas_matrix

typedef struct novas_matrix novas_matrix

A 3x3 matrix for coordinate transformations.

Since

1.1

See also

novas_transform, NOVAS_MATRIX_INIT, NOVAS_MATRIX_IDENTITY

novas_transform

typedef struct novas_transform novas_transform

A transformation between two astronomical coordinate systems for the same observer location and time.

This allows for more elegant, generic, and efficient coordinate transformations than the low-level NOVAS functions.

The transformation can be (should be) initialized via novas_make_transform(), or via novas_invert_transform().

Since

1.1

See also

novas_make_transform(), novas_invert_transform(), NOVAS_TRANSFORM_INIT

novas_transform_vector(), novas_transform_sky_pos()

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.

Referenced by novas_make_frame().

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 of observation and astronomical timescales	Time of observation
	xp	[mas] Earth orientation parameter, mean polar offset in x, e.g. from the IERS Bulletins, without diurnal libration and ocean tides. (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, mean polar offset in y, e.g. from the IERS Bulletins, without diurnal libration and ocean tides. (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]	Observing frames	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_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_diurnal_eop_at_time(), NOVAS_EARTH_INIT, NOVAS_FULL_ACCURACY, 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, novas_timespec::tt2tdb, and novas_observer::where.

Referenced by novas_equ_track(), and novas_hor_track().

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

	Observing frames	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.

Referenced by novas_moon_elp_posvel_fp(), and novas_moon_elp_sky_pos_fp().