Astrometric metadata. More...

#include <AstrometricMetadata.h>

Classes
struct	DescriptionItems
	A collection of strings describing the properties and parameters of an astrometric solution. More...

Public Member Functions
	AstrometricMetadata ()=default

	AstrometricMetadata (AstrometricMetadata &&)=default

	AstrometricMetadata (const AstrometricMetadata &x)

	AstrometricMetadata (const ImageWindow &window)

	AstrometricMetadata (ProjectionBase projection, WorldTransformation worldTransformation, int width, int height)

	AstrometricMetadata (XISFReader &reader)

virtual	~AstrometricMetadata ()

Rect	Bounds () const

void	Build (const PropertyArray &properties, const FITSKeywordArray &keywords, int width, int height)

String	Catalog () const

bool	CelestialToImage (DPoint &pI, const DPoint &pRD) const

Optional< TimePoint >	CreationTime () const

String	CreatorApplication () const

String	CreatorModule () const

String	CreatorOS () const

DescriptionItems	Description () const

double	FocalFromResolution (double resolution) const

bool	HasSplineWorldTransformation () const

int	Height () const

bool	ImageToCelestial (DPoint &pRD, const DPoint &pI) const

bool	IsValid () const

Optional< double >	LocationHeight () const

Optional< double >	LocationLatitude () const

Optional< double >	LocationLongitude () const

Optional< TimePoint >	ObservationEndTime () const

Optional< TimePoint >	ObservationMiddleTime () const

Optional< TimePoint >	ObservationStartTime () const

AstrometricMetadata &	operator= (AstrometricMetadata &&)=default

AstrometricMetadata &	operator= (const AstrometricMetadata &x)

Optional< double >	PixelSize () const

const ProjectionBase *	Projection () const

bool	RawImageToCelestial (DPoint &pRD, const DPoint &pI) const

IsoString	ReferenceSystem () const

double	Resolution () const

double	ResolutionFromFocal (double focal) const

double	Rotation (bool &flipped) const

double	SearchRadius () const

void	SetLocationHeight (double height)

void	SetLocationLatitude (double latitude)

void	SetLocationLongitude (double longitude)

void	SetObservationEndTime (TimePoint endTime)

void	SetObservationStartTime (TimePoint startTime)

void	SetPixelSize (double pixelSize)

void	SetReferenceSystem (const IsoString &refSys)

String	Summary () const

void	UndefineTimeAndLocationMetadata ()

void	UpdateBasicKeywords (FITSKeywordArray &keywords) const

void	UpdateProperties (PropertyArray &properties) const

void	UpdateWCSKeywords (FITSKeywordArray &keywords, bool generate=false) const

void	Validate (double tolerance=0.01) const

void	Verify (DPoint &centerErrors, DPoint &topLeftErrors, DPoint &topRightErrors, DPoint &bottomLeftErrors, DPoint &bottomRightErrors) const

int	Width () const

const WorldTransformation *	WorldTransform () const

void	Write (ImageWindow &window, bool notify=true) const

void	Write (XISFWriter &writer) const

Static Public Member Functions
static IsoString	ReferenceSystemFromMetadata (const PropertyArray &properties, const FITSKeywordArray &keywords)

static void	RemoveKeywords (FITSKeywordArray &keywords, bool removeCenterKeywords=true, bool removeScaleKeywords=true)

static void	RemoveProperties (ImageWindow &window, bool removeCenterProperties=true, bool removeScaleProperties=true)

static void	RemoveProperties (PropertyArray &properties, bool removeCenterProperties=true, bool removeScaleProperties=true)

static void	RescalePixelSizeKeywords (FITSKeywordArray &keywords, double scalingFactor)

static void	RescalePixelSizeProperties (ImageWindow &window, double scalingFactor)

static void	RescalePixelSizeProperties (PropertyArray &properties, double scalingFactor)

Detailed Description

Definition at line 112 of file AstrometricMetadata.h.

Constructor & Destructor Documentation

◆ AstrometricMetadata() [1/6]

pcl::AstrometricMetadata::AstrometricMetadata ( )

default

Default constructor. Constructs an uninitialized AstrometricMetadata object.

◆ AstrometricMetadata() [2/6]

pcl::AstrometricMetadata::AstrometricMetadata ( const AstrometricMetadata & x )

inline

Copy constructor.

Definition at line 158 of file AstrometricMetadata.h.

◆ AstrometricMetadata() [3/6]

pcl::AstrometricMetadata::AstrometricMetadata ( AstrometricMetadata && )

default

Move constructor.

◆ AstrometricMetadata() [4/6]

pcl::AstrometricMetadata::AstrometricMetadata	(	ProjectionBase *	projection,
		WorldTransformation *	worldTransformation,
		int	width,
		int	height
	)

Constructor from minimal data.

Parameters

projection	Pointer to a dynamically allocated projection system.
worldTransformation	Pointer to a dynamically allocated world coordinate transformation.
width	Width in pixels of the image with which this astrometric solution is associated.
height	Height in pixels of the image with which this astrometric solution is associated.

Ownership of the specified projection and worldTransformation objects will be transferred to this object, which will destroy and deallocate them when appropriate.

◆ AstrometricMetadata() [5/6]

pcl::AstrometricMetadata::AstrometricMetadata ( const ImageWindow & window )

Constructs an AstrometricMetadata object from the existing keywords and properties of an image window.

◆ AstrometricMetadata() [6/6]

pcl::AstrometricMetadata::AstrometricMetadata ( XISFReader & reader )

Constructs an AstrometricMetadata object from the existing keywords and properties of the currently selected image in an XISF reader.

◆ ~AstrometricMetadata()

virtual pcl::AstrometricMetadata::~AstrometricMetadata ( )

inlinevirtual

Virtual destructor.

Definition at line 227 of file AstrometricMetadata.h.

Member Function Documentation

◆ Bounds()

Rect pcl::AstrometricMetadata::Bounds ( ) const

inline

Returns the bounding rectangle in pixels of the image associated with the astrometric solution represented by this object.

The returned rectangle is equivalent to:

Rect( Width(), Height() )

Definition at line 467 of file AstrometricMetadata.h.

◆ Build()

void pcl::AstrometricMetadata::Build	(	const PropertyArray &	properties,
		const FITSKeywordArray &	keywords,
		int	width,
		int	height
	)

Regenerates the astrometric solution from standardized metadata.

Parameters

properties	A list of XISF image properties describing critical astrometry-related metadata items.
keywords	A list of FITS header keywords, which may contain a set of standard WCS keywords to define a linear world transformation from celestial to image coordinates. If the required metadata is available in the properties array, the corresponding keywords contained by this object will be ignored.
width	Width in pixels of the image with which this astrometric solution is associated.
height	Height in pixels of the image with which this astrometric solution is associated.

The following standard XISF properties will be extracted from the specified properties array, if available:

Instrument:Sensor:XPixelSize
Instrument:Telescope:FocalLength
Observation:CelestialReferenceSystem
Observation:Center:Dec
Observation:Center:RA
Observation:Equinox
Observation:Location:Elevation
Observation:Location:Latitude
Observation:Location:Longitude
Observation:Time:End
Observation:Time:Start

The following nonstandard XISF properties support our native astrometric solutions since core version 1.8.9-2:

PCL:AstrometricSolution:Catalog
PCL:AstrometricSolution:CelestialPoleNativeCoordinates
PCL:AstrometricSolution:CreationTime
PCL:AstrometricSolution:CreatorApplication
PCL:AstrometricSolution:CreatorModule
PCL:AstrometricSolution:CreatorOS
PCL:AstrometricSolution:Information
PCL:AstrometricSolution:LinearTransformationMatrix
PCL:AstrometricSolution:ProjectionSystem
PCL:AstrometricSolution:ReferenceCelestialCoordinates
PCL:AstrometricSolution:ReferenceImageCoordinates
PCL:AstrometricSolution:ReferenceNativeCoordinates

Spline-based astrometric solutions use an additional set of properties with the 'PCL:AstrometricSolution:SplineWorldTransformation:' identifier prefix.

XISF properties will always take precedence over existing equivalent FITS keywords.

If the specified properties array contains a valid serialization of spline parameters and control points, the astrometric solution will use a high-precision world transformation based on two-dimensional surface splines, which is capable of modeling local image distortions that are intractable with WCS linear transformations.

If this object contains valid metadata before calling this function, it will be disposed as appropriate, and a completely new astrometric solution will be constructed.

This member function can throw exceptions (of the Error class) if the specified properties and/or keywords arrays contain wrong or invalid data, or if the generated coordinate transformations are invalid (in the numerical or geometric sense).

◆ Catalog()

String pcl::AstrometricMetadata::Catalog ( ) const

inline

Returns the name of the star catalog used to generate this astrometric solution, or an empty string if the corresponding metadata item is not available.

Definition at line 720 of file AstrometricMetadata.h.

◆ CelestialToImage()

bool pcl::AstrometricMetadata::CelestialToImage	(	DPoint &	pI,
		const DPoint &	pRD
	)		const

inline

Transformation from celestial coordinates to image coordinates.

Parameters

[out]	pI	Reference to a point where the output image coordinates will be stored.
	pRD	Input equatorial spherical coordinates expressed in degrees. pRD.x is the right ascension and pRD.y is declination.

Returns true iff the specified celestial coordinates can be reprojected on the image coordinate system. Note that the output image coordinates can lie outside of the image bounds defined by [0,0]-[Width(),Height()].

The input coordinates specified in pRD are expected to be referred to the reference system of this astrometric solution, either ICRS or GCRS, as returned by the ReferenceSystem() member function.

See also: ImageToCelestial(), RawImageToCelestial()

Definition at line 853 of file AstrometricMetadata.h.

◆ CreationTime()

Optional<TimePoint> pcl::AstrometricMetadata::CreationTime ( ) const

inline

Returns the time this astrometric solution was generated, if available. When defined, the returned value should be represented in the UTC timescale.

Definition at line 710 of file AstrometricMetadata.h.

◆ CreatorApplication()

String pcl::AstrometricMetadata::CreatorApplication ( ) const

inline

Returns the name (typically with version numbers) of the software application used to generate this astrometric solution, or an empty string if the corresponding metadata item is not available.

Definition at line 730 of file AstrometricMetadata.h.

◆ CreatorModule()

String pcl::AstrometricMetadata::CreatorModule ( ) const

inline

Returns the name (typically with version numbers) of the software module or subsystem (such as a process or script) used to generate this astrometric solution, or an empty string if the corresponding metadata item is not available.

Definition at line 741 of file AstrometricMetadata.h.

◆ CreatorOS()

String pcl::AstrometricMetadata::CreatorOS ( ) const

inline

Returns the name of the operating system under which this astrometric solution was generated, or an empty string if the corresponding metadata item is not available. Currently this member function can return one of "FreeBSD", "Linux", "macOS", and "Windows".

Definition at line 752 of file AstrometricMetadata.h.

◆ Description()

DescriptionItems pcl::AstrometricMetadata::Description ( ) const

inline

Returns a collection of strings describing the metadata properties and parameters of this astrometric solution.

The returned object is a copy of an internal structure that is generated automatically as necessary and cached between successive function calls. This allows for efficient real-time representations of astrometric metadata and parameters.

Definition at line 1273 of file AstrometricMetadata.h.

◆ FocalFromResolution()

double pcl::AstrometricMetadata::FocalFromResolution ( double resolution ) const

inline

Returns the focal distance in millimeters, calculated from the specified image resolution expressed in seconds of arc per pixel.

Definition at line 510 of file AstrometricMetadata.h.

◆ HasSplineWorldTransformation()

bool pcl::AstrometricMetadata::HasSplineWorldTransformation ( ) const

inline

Returns true if this object uses a world transformation based on 2-D surface splines (or thin plate splines). Returns false if a standard WCS linear transformation is being used.

Definition at line 331 of file AstrometricMetadata.h.

◆ Height()

int pcl::AstrometricMetadata::Height ( ) const

inline

Returns the height in pixels of the image associated with the astrometric solution represented by this object.

Definition at line 452 of file AstrometricMetadata.h.

◆ ImageToCelestial()

bool pcl::AstrometricMetadata::ImageToCelestial	(	DPoint &	pRD,
		const DPoint &	pI
	)		const

inline

Transformation from image coordinates to celestial coordinates.

Parameters

[out]	pRD	Reference to a point where the output equatorial spherical coordinates will be stored, expressed in degrees. pRD.x will be the right ascension and pRD.y the declination. Output right ascensions are constrained to the [0,360) range. Output declinations are in the range [-90,+90].
	pI	Input image coordinates in pixels. The specified location can legally lie outside the image bounds defined by [0,0]-[Width(),Height()].

Returns true iff the specified point pI can be projected on the celestial sphere using this astrometric solution.

The output coordinates stored in pRD will be referred to the reference system of this astrometric solution, either ICRS or GCRS, as returned by the ReferenceSystem() member function.

See also: RawImageToCelestial(), CelestialToImage()

Definition at line 780 of file AstrometricMetadata.h.

◆ IsValid()

bool pcl::AstrometricMetadata::IsValid ( ) const

inline

Returns true iff this object is valid. A valid AstrometricMetadata instance defines a projection system and a world transformation.

Definition at line 268 of file AstrometricMetadata.h.

◆ LocationHeight()

Optional<double> pcl::AstrometricMetadata::LocationHeight ( ) const

inline

Returns the geodetic height of the observation location in meters, if available.

Definition at line 674 of file AstrometricMetadata.h.

◆ LocationLatitude()

Optional<double> pcl::AstrometricMetadata::LocationLatitude ( ) const

inline

Returns the geodetic latitude of the observation location, if available. The returned value is expressed in degrees in the range [-90,+90], reckoned positive north of the equator.

Definition at line 650 of file AstrometricMetadata.h.

◆ LocationLongitude()

Optional<double> pcl::AstrometricMetadata::LocationLongitude ( ) const

inline

Returns the geodetic longitude of the observation location, if available. The returned value is expressed in degrees in the range (-180,+180], reckoned positive eastward of the reference meridian.

Definition at line 621 of file AstrometricMetadata.h.

◆ ObservationEndTime()

Optional<TimePoint> pcl::AstrometricMetadata::ObservationEndTime ( ) const

inline

Returns the observation end time, if available. When defined, the returned value should be represented in the UTC timescale.

Definition at line 587 of file AstrometricMetadata.h.

◆ ObservationMiddleTime()

Optional<TimePoint> pcl::AstrometricMetadata::ObservationMiddleTime ( ) const

inline

Returns an estimate of the observation middle time. If both the start and end times are defined, returns the time point between them. If only the start time is defined, it is returned. Otherwise an undefined object is returned.

Definition at line 607 of file AstrometricMetadata.h.

◆ ObservationStartTime()

Optional<TimePoint> pcl::AstrometricMetadata::ObservationStartTime ( ) const

inline

Returns the observation start time, if available. When defined, the returned value should be represented in the UTC timescale.

Definition at line 569 of file AstrometricMetadata.h.

◆ operator=() [1/2]

AstrometricMetadata& pcl::AstrometricMetadata::operator= ( AstrometricMetadata && )

default

Move assignment operator. Returns a reference to this object.

◆ operator=() [2/2]

AstrometricMetadata& pcl::AstrometricMetadata::operator= ( const AstrometricMetadata & x )

inline

Copy constructor. Returns a reference to this object.

Definition at line 234 of file AstrometricMetadata.h.

◆ PixelSize()

Optional<double> pcl::AstrometricMetadata::PixelSize ( ) const

inline

Returns the physical pixel size in micrometers, if available.

Definition at line 690 of file AstrometricMetadata.h.

◆ Projection()

const ProjectionBase* pcl::AstrometricMetadata::Projection ( ) const

inline

Returns a pointer to the projection system of this astrometric solution. Returns nullptr if this object is not valid.

Definition at line 476 of file AstrometricMetadata.h.

◆ RawImageToCelestial()

bool pcl::AstrometricMetadata::RawImageToCelestial	(	DPoint &	pRD,
		const DPoint &	pI
	)		const

inline

Transformation from image coordinates to celestial coordinates, without enforcing a valid range of right ascensions.

Parameters

[out]	pRD	Reference to a point where the output equatorial spherical coordinates will be stored, expressed in degrees. pRD.x will be the right ascension and pRD.y the declination. Output right ascensions are not constrained to the [0,360) range. Output declinations are in the range [-90,+90].
	pI	Input image coordinates in pixels. The specified location can legally lie outside the image bounds defined by [0,0]-[Width(),Height()].

Returns true iff the specified point pI can be projected on the celestial sphere using this astrometric solution.

The output coordinates stored in pRD will be referred to the reference system of this astrometric solution, either ICRS or GCRS, as returned by the ReferenceSystem() member function.

This function is useful for interpolation schemes where discontinuities caused by zero crossings in right ascension, i.e. abrupt changes from 360 to 0 degrees, are not admissible numerically. Right ascensions returned by this function can be larger than 360 degrees or less than zero, ensuring smooth transitions.

See also: ImageToCelestial(), CelestialToImage()

Definition at line 826 of file AstrometricMetadata.h.

◆ ReferenceSystem()

IsoString pcl::AstrometricMetadata::ReferenceSystem ( ) const

inline

Returns the name of the coordinate reference system to which this astrometric solution has been referred.

This corresponds to the reference system of the coordinates of the reference point sources (usually stars with data acquired from astrometric catalogs) used to compute the astrometric solution. The current implementation supports the following reference systems:

ICRS

Reference point source positions are astrometric: they include corrections for space motion (proper motions, annual parallax and radial velocity, when available) and gravitational deflection of light, but not annual aberration. This is the default reference system that is assumed when none is specified or acquired from existing metadata.

GCRS

Reference point source positions are proper: they include corrections for space motion (proper motions, annual parallax and radial velocity, when available), gravitational deflection of light, and annual aberration (rigorous relativistic model).

Other nonstandard values can be returned by this function, such as different values of the RADESYS FITS keyword. Such values will be preserved but won't be supported by standard platform implementations.

Definition at line 402 of file AstrometricMetadata.h.

References pcl::GenericString< T, R, A >::IsEmpty().

◆ ReferenceSystemFromMetadata()

static IsoString pcl::AstrometricMetadata::ReferenceSystemFromMetadata	(	const PropertyArray &	properties,
		const FITSKeywordArray &	keywords
	)

static

Returns the name of the reference system of celestial coordinates derived from the specified image metadata.

Parameters

properties	A list of XISF image properties.
keywords	A list of FITS header keywords.

The reference system will be inferred from the following metadata items:

The standard XISF property 'Observation:CelestialReferenceSystem'

The standard FITS keyword 'RADESYS'.

In case of metadata duplicity, XISF properties always take precedence over FITS keywords.

Typical returned values are "ICRS" and "GCRS". If no valid reference system can be deduced from the specified metadata, this function returns an empty string.

◆ RemoveKeywords()

static void pcl::AstrometricMetadata::RemoveKeywords	(	FITSKeywordArray &	keywords,
		bool	removeCenterKeywords = `true`,
		bool	removeScaleKeywords = `true`
	)

static

Removes astrometry-related FITS header keywords from the specified keywords array. This includes some basic instrumental and observational keywords, as well as the following keywords:

RADESYS
EQUINOX
EPOCH
CTYPE1
CTYPE2
CRVAL1
CRVAL2
CRPIX1
CRPIX2
CD1_1
CD1_2
CD2_1
CD2_2
PC1_1
PC1_2
PC2_1
PC2_2
CDELT1
CDELT2
CROTA1
CROTA2
PV1_1
PV1_2
PV1_3
PV1_4
LONPOLE
LATPOLE

If removeCenterKeywords is true, the following keywords will also be removed:

RA
OBJCTRA
DEC
OBJCTDEC

If removeScaleKeywords is true, the following keywords will also be removed:

FOCALLEN
XPIXSZ
YPIXSZ
PIXSIZE

◆ RemoveProperties() [1/2]

static void pcl::AstrometricMetadata::RemoveProperties	(	ImageWindow &	window,
		bool	removeCenterProperties = `true`,
		bool	removeScaleProperties = `true`
	)

static

Removes astrometry-related XISF properties from the specified window's main view.

See RemoveProperties( PropertyArray&, bool, bool ) for detailed information.

◆ RemoveProperties() [2/2]

static void pcl::AstrometricMetadata::RemoveProperties	(	PropertyArray &	properties,
		bool	removeCenterProperties = `true`,
		bool	removeScaleProperties = `true`
	)

static

Removes astrometry-related XISF properties from the specified properties array.

If removeCenterProperties is true, the following properties will also be removed:

Observation:Center:RA
Observation:Center:Dec
Observation:Center:X
Observation:Center:Y
Observation:CelestialReferenceSystem
Observation:Equinox

If removeScaleProperties is true, the following properties will also be removed:

Instrument:Telescope:FocalLength
Instrument:Sensor:XPixelSize
Instrument:Sensor:YPixelSize

The following properties will always be removed:

Observation:CelestialReferenceSystem
Observation:Equinox
PCL:AstrometricSolution:Catalog
PCL:AstrometricSolution:CelestialPoleNativeCoordinates
PCL:AstrometricSolution:CreationTime
PCL:AstrometricSolution:CreatorApplication
PCL:AstrometricSolution:CreatorModule
PCL:AstrometricSolution:CreatorOS
PCL:AstrometricSolution:Information
PCL:AstrometricSolution:LinearTransformationMatrix
PCL:AstrometricSolution:ProjectionSystem
PCL:AstrometricSolution:ReferenceCelestialCoordinates
PCL:AstrometricSolution:ReferenceImageCoordinates
PCL:AstrometricSolution:ReferenceNativeCoordinates

Finally, for spline-based astrometric solutions, all existing properties with the 'PCL:AstrometricSolution:SplineWorldTransformation:' identifier prefix will also be removed.

◆ RescalePixelSizeKeywords()

static void pcl::AstrometricMetadata::RescalePixelSizeKeywords	(	FITSKeywordArray &	keywords,
		double	scalingFactor
	)

static

Rescales the values of existing FITS header keywords defining physical pixel dimensions in the specified keywords array.

This function multiplies the values of the following keywords by the specified scalingFactor:

XPIXSZ
YPIXSZ
PIXSIZE

This is useful in cases where a geometric transformation has to be applied to an image to modify its scale, such as a resampling operation.

◆ RescalePixelSizeProperties() [1/2]

static void pcl::AstrometricMetadata::RescalePixelSizeProperties	(	ImageWindow &	window,
		double	scalingFactor
	)

static

Rescales the values of existing XISF properties defining physical pixel dimensions for the specified window's main view.

See RescalePixelSizeProperties( PropertyArray&, double ) for detailed information.

◆ RescalePixelSizeProperties() [2/2]

static void pcl::AstrometricMetadata::RescalePixelSizeProperties	(	PropertyArray &	properties,
		double	scalingFactor
	)

static

Rescales the values of existing XISF properties defining physical pixel dimensions in the specified properties array.

This function multiplies the values of the following properties by the specified scalingFactor:

Instrument:Sensor:XPixelSize
Instrument:Sensor:YPixelSize

This is useful in cases where a geometric transformation has to be applied to an image to modify its scale, such as a resampling operation.

◆ Resolution()

double pcl::AstrometricMetadata::Resolution ( ) const

inline

Returns the resolution of the image in degrees per pixel.

This value usually is an approximation since it changes across the image. It should only be used for informative purposes.

Definition at line 533 of file AstrometricMetadata.h.

◆ ResolutionFromFocal()

double pcl::AstrometricMetadata::ResolutionFromFocal ( double focal ) const

inline

Returns the image resolution in seconds of arc per pixel, calculated from the specified focal distance in millimeters.

Definition at line 501 of file AstrometricMetadata.h.

References pcl::Const< T >::pi().

◆ Rotation()

double pcl::AstrometricMetadata::Rotation ( bool & flipped ) const

Returns the angle of rotation of the Y axis of the image with respect to the north direction, as represented on a flat projection of the celestial sphere. A rotation angle of zero aligns north along the positive Y axis. A positive rotation angle rotates the Y axis from north to east.

The returned value is the rotation angle of the projection in degrees. The flipped variable will be true iff the projection is mirrored on the east-west direction.

◆ SearchRadius()

double pcl::AstrometricMetadata::SearchRadius ( ) const

inline

Returns the radius in degrees of a circular region of the sky circumscribed to the bounding rectangle of this astrometric solution.

The returned radius can be used to perform search operations with star catalogs and solar system ephemerides.

Definition at line 545 of file AstrometricMetadata.h.

◆ SetLocationHeight()

void pcl::AstrometricMetadata::SetLocationHeight ( double height )

inline

Sets the geodetic height of the observation location in meters.

Definition at line 682 of file AstrometricMetadata.h.

◆ SetLocationLatitude()

void pcl::AstrometricMetadata::SetLocationLatitude ( double latitude )

inline

Sets the geodetic latitude of the observation location. The specified latitude must be expressed in degrees and must be in the range [-90,+90], reckoned positive north of the equator.

If a value out of the valid range is specified, this function will throw an Error exception.

Definition at line 663 of file AstrometricMetadata.h.

◆ SetLocationLongitude()

void pcl::AstrometricMetadata::SetLocationLongitude ( double longitude )

inline

Sets the geodetic longitude of the observation location. The specified longitude must be expressed in degrees and can be either in the range [0,360] or [-180,+180], reckoned positive eastward.

If a value out of the valid range is specified, this function will throw an Error exception.

Definition at line 634 of file AstrometricMetadata.h.

◆ SetObservationEndTime()

void pcl::AstrometricMetadata::SetObservationEndTime ( TimePoint endTime )

inline

Sets the observation end time. The specified endTime value should be represented in the UTC timescale.

Definition at line 596 of file AstrometricMetadata.h.

◆ SetObservationStartTime()

void pcl::AstrometricMetadata::SetObservationStartTime ( TimePoint startTime )

inline

Sets the observation start time. The specified startTime value should be represented in the UTC timescale.

Definition at line 578 of file AstrometricMetadata.h.

◆ SetPixelSize()

void pcl::AstrometricMetadata::SetPixelSize ( double pixelSize )

inline

Redefines the physical pixel size in micrometers. Recalculates the focal distance as a function of the pixel size.

Definition at line 699 of file AstrometricMetadata.h.

◆ SetReferenceSystem()

void pcl::AstrometricMetadata::SetReferenceSystem ( const IsoString & refSys )

inline

Sets the coordinate reference system. See ReferenceSystem() for more information and supported values.

Definition at line 411 of file AstrometricMetadata.h.

◆ Summary()

String pcl::AstrometricMetadata::Summary ( ) const

Returns a printable textual representation of the metadata properties and parameters of the astrometric solution represented by this object.

◆ UndefineTimeAndLocationMetadata()

void pcl::AstrometricMetadata::UndefineTimeAndLocationMetadata ( )

inline

Undefines the optional metadata items for observation time (start and end times) and geodetic coordinates (longitude, latitude and height).

This function is useful to propagate the astrometric solution to other images, for example during an image registration task, without altering image-specific observational properties.

Definition at line 1089 of file AstrometricMetadata.h.

◆ UpdateBasicKeywords()

void pcl::AstrometricMetadata::UpdateBasicKeywords ( FITSKeywordArray & keywords ) const

Updates the specified keywords array with basic astrometric FITS header keywords. This includes a number of standard instrumental and observational keywords, as well as some customary nonstandard keywords, included for compatibility with third-party applications:

RA
OBJCTRA
DEC
OBJCTDEC
DATE-OBS
DATE-END
OBSGEO-L
LONG-OBS
OBSGEO-B
LAT-OBS
OBSGEO-H
ALT-OBS
FOCALLEN
XPIXSZ
YPIXSZ
PIXSIZE

Keywords are updated when the corresponding metadata items are available.

◆ UpdateProperties()

void pcl::AstrometricMetadata::UpdateProperties ( PropertyArray & properties ) const

Updates the specified properties array with a restricted set of view properties to reflect the state of this astrometric solution.

The following standard XISF properties will be created or redefined:

Instrument:Sensor:XPixelSize
Instrument:Sensor:YPixelSize
Instrument:Telescope:FocalLength
Observation:CelestialReferenceSystem
Observation:Center:Dec
Observation:Center:RA
Observation:Equinox

The following properties can be removed if the transformation is valid, since the default coordinate reference point is the geometric center of the image, which is used to calculate the values of the standard Observation:Center:RA and Observation:Center:Dec properties:

Observation:Center:X
Observation:Center:Y

The following properties will be created or redefined if the corresponding metadata items are available, or removed otherwise:

Observation:Location:Elevation
Observation:Location:Latitude
Observation:Location:Longitude
Observation:Time:End
Observation:Time:Start

The following nonstandard properties (which support our native astrometric solutions since core version 1.8.9-2) will be created, redefined, or removed as necessary:

PCL:AstrometricSolution:Catalog
PCL:AstrometricSolution:CelestialPoleNativeCoordinates
PCL:AstrometricSolution:CreationTime
PCL:AstrometricSolution:CreatorApplication
PCL:AstrometricSolution:CreatorModule
PCL:AstrometricSolution:CreatorOS
PCL:AstrometricSolution:Information
PCL:AstrometricSolution:LinearTransformationMatrix
PCL:AstrometricSolution:ProjectionSystem
PCL:AstrometricSolution:ReferenceCelestialCoordinates
PCL:AstrometricSolution:ReferenceImageCoordinates
PCL:AstrometricSolution:ReferenceNativeCoordinates

For spline-based astrometric solutions, an additional set of properties with the 'PCL:AstrometricSolution:SplineWorldTransformation:' identifier prefix will also be created, redefined or removed as necessary.

◆ UpdateWCSKeywords()

void pcl::AstrometricMetadata::UpdateWCSKeywords	(	FITSKeywordArray &	keywords,
		bool	generate = `false`
	)		const

Updates or removes standard WCS FITS header keywords in the specified keywords array:

RADESYS
EQUINOX
EPOCH
CTYPE1
CTYPE2
CRVAL1
CRVAL2
CRPIX1
CRPIX2
CD1_1
CD1_2
CD2_1
CD2_2
PC1_1
PC1_2
PC2_1
PC2_2
CDELT1
CDELT2
CROTA1
CROTA2
PV1_1
PV1_2
PV1_3
PV1_4
LONPOLE
LATPOLE

if generate is true, a new set of WCS FITS keywords will be generated (by replacing existing ones or creating them as necessary) in the keywords array.

If generate is false, existing WCS FITS keywords will be removed and no new ones will be generated. This is the default behavior since PixInsight core version 1.8.9-2, when our native astrometric solutions no longer depend on FITS keywords.

◆ Validate()

void pcl::AstrometricMetadata::Validate ( double tolerance = 0.01 ) const

Checks that this astrometric solution is valid and can perform coherent coordinate transformations.

Parameters

tolerance Maximum difference in pixels allowed for validation. The default value is 0.01 pixels.

This routine performs two successive coordinate transformations, from image to celestial and from celestial to image coordinates, computed for the geometric center of the image. If the absolute value of the difference between the initial and final image coordinates is greater than the specified tolerance in pixels, for one or both axes, an Error exception is thrown.

This function also throws an Error exception if the solution has not been initialized, or if it cannot perform valid coordinate transformations.

◆ Verify()

void pcl::AstrometricMetadata::Verify	(	DPoint &	centerErrors,
		DPoint &	topLeftErrors,
		DPoint &	topRightErrors,
		DPoint &	bottomLeftErrors,
		DPoint &	bottomRightErrors
	)		const

Checks that this astrometric solution is valid and can perform coherent coordinate transformations, and returns the reprojection errors measured at the center and the four corners of the image.

Parameters

[out]	centerErrors	Reprojection errors at the geometric center of the image, or (Width()/2,Height()/2) image coordinates.
[out]	topLeftErrors	Reprojection errors at (0,0) image coordinates.
[out]	topRightErrors	Reprojection errors at (Width(),0) image coordinates.
[out]	bottomLeftErrors	Reprojection errors at (0,Height()) image coordinates.
[out]	bottomRightErrors	Reprojection errors at (Width(),Height()) image coordinates.

This routine performs five successive coordinate transformations, from image to celestial and from celestial to image coordinates, computed for the four corners and the geometric center of the image. The reported values in the specified point variables are the differences between the initial and final image coordinates, on the X and Y axes, in pixels.

This function throws an Error exception if the solution has not been initialized, or if it cannot perform valid coordinate transformations.

◆ Width()

int pcl::AstrometricMetadata::Width ( ) const

inline

Returns the width in pixels of the image associated with the astrometric solution represented by this object.

Definition at line 443 of file AstrometricMetadata.h.

◆ WorldTransform()

const WorldTransformation* pcl::AstrometricMetadata::WorldTransform ( ) const

inline

Returns a pointer to the world coordinate transformation of this astrometric solution. Returns nullptr if this object is not valid.

Definition at line 485 of file AstrometricMetadata.h.

◆ Write() [1/2]

void pcl::AstrometricMetadata::Write	(	ImageWindow &	window,
		bool	notify = `true`
	)		const

Updates the keywords and properties of an image window to represent this astrometric solution.

The pixel dimensions of the image in the target window must be coherent with this astrometric solution. If that is not true, this member function will throw an Error exception. An Error exception will also be thrown if this object does not define a valid astrometric solution.

See the UpdateBasicKeywords(), UpdateWCSKeywords() and UpdateProperties() member functions for information on the metadata items modified by this function.

◆ Write() [2/2]

void pcl::AstrometricMetadata::Write ( XISFWriter & writer ) const

Updates the keywords and properties of the current image in an XISF writer to store the astrometric solution represented by this object.

The caller must ensure that the pixel dimensions of the current image in the target XISF writer, that is, the width and height of the image being generated, are coherent with this astrometric solution. Currently this condition cannot be verified or enforced by this member function.

This function will throw an Error exception if this object does not define a valid astrometric solution.

See the UpdateBasicKeywords(), UpdateWCSKeywords() and UpdateProperties() member functions for information on the metadata items modified by this function.

The documentation for this class was generated from the following file:

AstrometricMetadata.h

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ AstrometricMetadata() [1/6]

◆ AstrometricMetadata() [2/6]

◆ AstrometricMetadata() [3/6]

◆ AstrometricMetadata() [4/6]

◆ AstrometricMetadata() [5/6]

◆ AstrometricMetadata() [6/6]

◆ ~AstrometricMetadata()

Member Function Documentation

◆ Bounds()

◆ Build()

◆ Catalog()

◆ CelestialToImage()

◆ CreationTime()

◆ CreatorApplication()

◆ CreatorModule()

◆ CreatorOS()

◆ Description()

◆ FocalFromResolution()

◆ HasSplineWorldTransformation()

◆ Height()

◆ ImageToCelestial()

◆ IsValid()

◆ LocationHeight()

◆ LocationLatitude()

◆ LocationLongitude()

◆ ObservationEndTime()

◆ ObservationMiddleTime()

◆ ObservationStartTime()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ PixelSize()

◆ Projection()

◆ RawImageToCelestial()

◆ ReferenceSystem()

◆ ReferenceSystemFromMetadata()

◆ RemoveKeywords()

◆ RemoveProperties() [1/2]

◆ RemoveProperties() [2/2]

◆ RescalePixelSizeKeywords()

◆ RescalePixelSizeProperties() [1/2]

◆ RescalePixelSizeProperties() [2/2]

◆ Resolution()

◆ ResolutionFromFocal()

◆ Rotation()

◆ SearchRadius()

◆ SetLocationHeight()

◆ SetLocationLatitude()

◆ SetLocationLongitude()

◆ SetObservationEndTime()

◆ SetObservationStartTime()

◆ SetPixelSize()

◆ SetReferenceSystem()

◆ Summary()

◆ UndefineTimeAndLocationMetadata()

◆ UpdateBasicKeywords()

◆ UpdateProperties()

◆ UpdateWCSKeywords()

◆ Validate()

◆ Verify()

◆ Width()

◆ WorldTransform()

◆ Write() [1/2]

◆ Write() [2/2]