PCL
Public Member Functions | Static Public Member Functions | List of all members
pcl::StarDatabaseFile Class Referenceabstract
Star Catalogs and Point Source Databases

Point source and star catalog database files (XPSD format). More...

#include <StarDatabaseFile.h>

+ Inheritance diagram for pcl::StarDatabaseFile:

Public Member Functions

 StarDatabaseFile ()=default
 
 StarDatabaseFile (const StarDatabaseFile &)=delete
 
 StarDatabaseFile (const String &filePath)
 
 StarDatabaseFile (StarDatabaseFile &&)=default
 
virtual ~StarDatabaseFile () noexcept(false)
 
void Close ()
 
const String & FilePath () const
 
bool IsOpen () const
 
float MagnitudeHigh () const
 
float MagnitudeLow () const
 
const XPSD::Metadata & Metadata () const
 
void Open (const String &filePath)
 
StarDatabaseFile & operator= (const StarDatabaseFile &)=delete
 
StarDatabaseFile & operator= (StarDatabaseFile &&)=default
 
const XPSD::Statistics & Statistics () const
 

Static Public Member Functions

static void Serialize (const String &filePath, const XPSD::Metadata &metadata, const XPSD::Statistics &statistics, float magnitudeLow, float magnitudeHigh, const Array< XPSD::IndexTree > &index, const ByteArray &data, const Compression *compression=nullptr, const String &parameters=String())
 

Detailed Description

This class implements fast access to point source data stored in XPSD files (Extensible Point Source Database format). It also implements serialization of new XPSD files from existing point source or star catalog data.

On the PixInsight/PCL platform, the XPSD file format allows for fast and efficient access to large star catalogs, such as Gaia (as of writing this documentation the Gaia DR2 and EDR3 catalogs are available) or PPMXL. The XPSD format allows for serialization of general purpose star catalogs, with special emphasis on astrometric and photometric data.

Definition at line 506 of file StarDatabaseFile.h.

Constructor & Destructor Documentation

◆ StarDatabaseFile() [1/4]

pcl::StarDatabaseFile::StarDatabaseFile ( )
default

Default constructor.

Constructs an invalid instance that cannot be used until initialized by calling the Open() member function.

◆ StarDatabaseFile() [2/4]

pcl::StarDatabaseFile::StarDatabaseFile ( const String &  filePath)
inline

Constructs a &StarDatabaseFile instance initialized from the specified point source database file in XPSD format.

In the event of errors or invalid data, this constructor will throw the appropriate Error exception.

Definition at line 525 of file StarDatabaseFile.h.

◆ StarDatabaseFile() [3/4]

pcl::StarDatabaseFile::StarDatabaseFile ( StarDatabaseFile &&  )
default

Move constructor.

◆ StarDatabaseFile() [4/4]

pcl::StarDatabaseFile::StarDatabaseFile ( const StarDatabaseFile &  )
delete

Deleted copy constructor. StarDatabaseFile instances are unique, hence cannot be copied.

◆ ~StarDatabaseFile()

virtual pcl::StarDatabaseFile::~StarDatabaseFile ( )
inlinevirtualnoexcept

Virtual destructor.

Definition at line 555 of file StarDatabaseFile.h.

Member Function Documentation

◆ Close()

void pcl::StarDatabaseFile::Close ( )

Closes the point source database file represented by this object and resets all internal structures to a default, uninitialized state.

If a previous file was already opened by this instance, it will be closed and all associated control and file indexing structures will be destroyed and deallocated. If no file is currently open, calling this member has no effect.

◆ FilePath()

const String& pcl::StarDatabaseFile::FilePath ( ) const
inline

Returns the path of the point source database file represented by this object. Returned file paths are always absolute, full file paths.

Definition at line 598 of file StarDatabaseFile.h.

◆ IsOpen()

bool pcl::StarDatabaseFile::IsOpen ( ) const
inline

Returns true iff this object has an open database file and is ready for point source data retrieval.

Definition at line 589 of file StarDatabaseFile.h.

◆ MagnitudeHigh()

float pcl::StarDatabaseFile::MagnitudeHigh ( ) const
inline

Returns the high limiting magnitude of this database file. All contained sources should have magnitudes less than or equal to the value returned by this function.

Definition at line 618 of file StarDatabaseFile.h.

◆ MagnitudeLow()

float pcl::StarDatabaseFile::MagnitudeLow ( ) const
inline

Returns the low limiting magnitude of this database file. All contained sources should have magnitudes greater than the value returned by this function.

Definition at line 608 of file StarDatabaseFile.h.

◆ Metadata()

const XPSD::Metadata& pcl::StarDatabaseFile::Metadata ( ) const
inline

Returns a reference to the (immutable) set of metadata items available in the point source database file loaded by this object.

Definition at line 627 of file StarDatabaseFile.h.

Referenced by pcl::GaiaDatabaseFile::GaiaDatabaseFile().

◆ Open()

void pcl::StarDatabaseFile::Open ( const String &  filePath)

Initializes this object to provide access to the specified point source database file in XPSD format.

This member function opens an existing file at the specified filePath, loads and parses its XML header, and loads the file indexes ready for fast access to point source data. The file will remain open until this object is destroyed, or until a new call to this function is made.

If a previous file was already opened by this instance, it will be closed and all associated control and file indexing structures will be destroyed and deallocated, before accessing the new file.

◆ operator=() [1/2]

StarDatabaseFile& pcl::StarDatabaseFile::operator= ( const StarDatabaseFile &  )
delete

Deleted copy assignment operator. StarDatabaseFile instances are unique, hence cannot be copied.

◆ operator=() [2/2]

StarDatabaseFile& pcl::StarDatabaseFile::operator= ( StarDatabaseFile &&  )
default

Move assignment operator. Returns a reference to this object.

◆ Serialize()

static void pcl::StarDatabaseFile::Serialize ( const String &  filePath,
const XPSD::Metadata &  metadata,
const XPSD::Statistics &  statistics,
float  magnitudeLow,
float  magnitudeHigh,
const Array< XPSD::IndexTree > &  index,
const ByteArray &  data,
const Compression *  compression = nullptr,
const String &  parameters = String() 
)
static

Generates a file to store a point source database in XPSD format.

Parameters
filePathPath to the file that will be generated in the local filesystem. The file name should carry the '.xpsd' suffix.
metadataReference to an XPSD::Metadata structure with optional metadata information that will be included in the generated XPSD file.
statisticsReference to an XPSD::Statistics structure with statistical and structural information about the XPSD database, which will be included in the generated XPSD file.
magnitudeLowLow limiting magnitude. All point sources serialized in the data array should have magnitudes greater than the value of this parameter.
magnitudeHighHigh limiting magnitude. All point sources serialized in the data array should have magnitudes less than or equal to the value of this parameter.
indexArray of quadtree index structures.
dataSerialized point source data.
compressionPointer to a Compression object used to compress point source data blocks (leaf node data), or nullptr if no compression has been applied. If specified, this object will be used exclusively to gather information about the compression algorithm and parameters used, not to compress any data.
parametersSpecial parameters for interpretation of the serialized point source data. Is a nonempty string is specified, it will be set as the value of the "parameters" attribute of the Data element, and will be available as the m_parameters protected field after deserialization.

In the event of invalid, incongruent or malformed data, or if an I/O error occurs, this function will throw an Error exception.

Warning
If a file already exists at the specified path, its previous contents will be lost after calling this function.

◆ Statistics()

const XPSD::Statistics& pcl::StarDatabaseFile::Statistics ( ) const
inline

Returns a reference to the (immutable) set of statistical and structural information items available in the point source database file loaded by this object.

Definition at line 637 of file StarDatabaseFile.h.

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