Astro::Catalog - A generic API for stellar catalogs


    $catalog = new Astro::Catalog(Stars => \@array);
    $catalog = new Astro::Catalog(Format => 'Cluster', File => $file_name);
    $catalog = new Astro::Catalog(Format => 'JCMT', Data => $scalar);
    $catalog = new Astro::Catalog(Format => 'Simple', Data => \*STDIN);
    $catalog = new Astro::Catalog(Format => 'VOTable', Data => \@lines);


Stores generic meta-data about an astronomical catalog. Takes a hash with an array reference as an argument. The array should contain a list of Astro::Catalog::Item objects. Alternatively it takes a catalog format and either the name of a catalog file or a reference to a scalar, glob or array.


For input the Astro::Catalog module understands Cluster, Simple, JCMT, TST, STL, GaiaPick, the UKIRT internal Bright Star catalog format and (a very simple parsing) of VOTable.

The module can output all of these formats except TST (which is input only).




Create a new instance from a hash of options

    $catalog = new Astro::Catalog(Stars  => \@array);
    $catalog = new Astro::Catalog(Format => 'Cluster', File => $file_name);
    $catalog = new Astro::Catalog(Format => 'JCMT', Data => $scalar);

returns a reference to an Astro::Catalog object. See the configure method for a list of allowed arguments.

Output Methods


Will serialise the catalog object in a variety of file formats using pluggable IO, see the Astro::Catalog::IO classes

        File => $file_name, Format => $file_type, [%opts])
    or die $catalog->errstr;

returns true on sucess and false if the write failed (the reason can be obtained using the errstr method). The %opts are optional arguments and are dependent on the output format chosen. Current valid output formats are 'Simple', 'Cluster', 'JCMT' and 'VOTable'.

The File argument can refer to a file name on disk (simple scalar), a glob (eg \*STDOUT), an IO::Handle object (for example something returned by the File::Temp constructor) a reference to a scalar (\$content) or reference to an array. For the last two options, the contents of the catalog file are stored in the scalar or in the array (a line per array entry with no new lines).

Accessor Methods


Return (or set) the origin of the data. For example, USNOA2, GSC for catalog queries, or 'JCMT' for the JCMT pointing catalog. No constraint is placed on the content of this parameter.

    $origin = $catalog->origin();

Error string associated with any error. Can only be trusted immediately after a call that sets it (eg write_catalog).


Set or return the preferred magnitude type to be returned from the Astro::Catalog::Item->get_magnitude() method.

    my $type = $catalog->preferred_magnitude_type;

Return the number of stars in the catalog (post filter).

    $num = $catalog->sizeof();

Returns the total number of stars in the catalog without filtering.


Push a new star (or stars) onto the end of the Astro::Catalog object


returns the number of stars now in the Catalog object (even if no arguments were supplied). The method guarantees that the stars are pushed onto the internal original list and the filtered/sorted version.

Currently no check is made to make sure that the star is already on one of the two lists.


Pop a star from the end of the Astro::Catalog object. This forces a copy of the array if one has not already been made (ie the original version is unchanged).

    $star = $catalog->popstar();

the method deletes the star and returns the deleted Astro::Catalog::Item object.


Return Astro::Catalog::Item objects that have the given ID. This forces a copy of the array if one has not already been made (ie the original version is unchanged).

    @stars = $catalog->popstarbyid( $id );

The method deletes the stars and returns the deleted Astro::Catalog::Item objects. If no star exists with the given ID, the method returns an empty list.

If called in scalar context this method returns an array reference, and if called in list context returns an array of Astro::Catalog::Item objects.

This is effectively an inverse filter (see filter_by_id for complementary method).


Return all the stars in the catalog in their original ordering and without filtering.

    @allstars = $catalog->allstars();
    $ref = $catalog->allstars();

In list context returns all the stars, in scalar context returns a reference to the internal array. This allows the primary array to be modified in place so use this with care.

Addendum: This is pretty much for internal use only, but if you do this


you repalce the stars array with the array passed. Don't do this, it's bad!


Return a list of all the Astro::Catalog::Item objects that are currently valid and in the current order. This method may well return different stars to the allstars method depending on the current sort in scope.

    @stars = $catalog->stars();

in list context the copy of the array is returned, while in scalar context a reference to the array is return. In scalar context, the referenced array will always be that of the current list of valid stars. If the current list is empty the primary list will be copied into the current array so that it can be modified independently of the original list. This may cost you a lot of memory. Note that changes to the array ordering or content may be lost in this case whenever the reset_list method is used.


Return the Astro::Catalog::Item object at index $index

    $star = $catalog->starbyindex($index);

the first star is at index 0 (not 1). Returns undef if no arguments are provided.


Set the field centre and radius of the catalog (if appropriate)

        RA     => $ra,
        Dec    => $dec,
        Radius => $radius,
        Coords => new Astro::Coords());

RA and Dec must be given together or as Coords. Coords (an Astro::Coords object) supercedes RA/Dec.


Set the field centre radius. Must be in arcminutes.


Set the field centre coordinates with an Astro::Coords object.


Return the Astro::Coords object associated with the field centre.

    $c = $catalog->get_coords();

Return the RA of the catalog field centre in sexagesimal, space-separated format. Returns undef if no coordinate supplied.

    $ra = $catalog->get_ra();

Return the Dec of the catalog field centre in sexagesimal space-separated format with leading sign.

    $dec = $catalog->get_dec();

Return the radius of the catalog from the field centre

    $radius = $catalog->get_radius();

If set this must contain an Astro::Coords object that can be used as a reference position. When a reference is supplied distances will be calculated from each catalog target to the reference. It will also be possible to sort by distance.

    $ref = $catalog->reference;

If a reference position is not specified explicitly the field centre will be used instead (if defined).


The reference time used for coordinate calculations. Extracted from the reference coordinate object if one exists and no override has been specified. If neither a default setting has been made and no reference exists the current time is returned.

    $reftime = $src->reftime();


Time must be a Time::Piece object. This is only really important for moving objects such as planets or asteroids or for occasions when you are calcualting azimuth or elevation.


The observation date/time of the field.

    $fielddate = $src->fielddate;


Date must be a Time::Piece object. This defaults to the current time when the Astro::Catalog object was instantiated.


If this flag is true, a reset_list will automatically remove targets that are not observable (as determined by filter_by_observability which will be invoked).

Default is false.


Method to contain information not handled by other methods. This is analogous to the Astro::Catalog::Item::misc method, and should also typically be used to store a hash reference.

General Methods


Configures the object from multiple pieces of information.

    $newcat = $catalog->configure(%options);

Takes a hash as argument with the list of keywords. Supported options are:

    Format => Format of supplied catalog
    File => File name for catalog on disk. Not used if 'Data' supplied.
    Data => Contents of catalog, either as a scalar variable,
            reference to array of lines or reference to glob (file handle).
            This key is used in preference to 'File' if both are present

    Stars => Array of Astro::Catalog::Item objects. Supercedes all other options.
    ReadOpt => Reference to hash of options to be forwarded onto the
               format specific catalog reader. See the IO documentation
               for details.

If Format is supplied without any other options, a default file is requested from the class implementing the formatted read. If no default file is forthcoming the method croaks.

If no options are specified the method does nothing, assumes you will be supplying stars at a later time.

The options are case-insensitive.

Note that in some cases (when reading a catalog) this method will act as a constructor. In any case, always returns a catalog object (either the same one that went in or a modified one).

API uncertainty - in principal Data is not needed since File could be overloaded (in a similar way to write_catalog).


Forces the star list to return to the original unsorted, unfiltered catalog list.


If auto_filter_observability is true, the list will be immediately filtered for observability.


Force the specified reference time into the coordinate object associated with each star (in the current list). This ensures that calculations on the catalog entries are all calculated for the same time.


After this, the times in the coordinate objects will be set and will no longer reflect current time (if they had it originally).


Calculate the X and Y positions for every item in the catalog, if they have an RA and Dec.


The supplied argument must be a Starlink::AST::FrameSet.


All these filters work on a copy of the full star list. The filters are cumulative.


Generate a filtered catalog where only those targets that are observable are present (assumes that the current state of the coordinate objects is correct but will use the reference time returned by reftime). ie the object is returned to its original state and then immediately filtered by observability. Any stars without coordinates are also filtered. Starts from the current star list (which may already have been filtered).

    @new = $catalog->filter_by_observability();

Returns the newly selected stars (as if the stars method was called immediately, unless called in a non-list context.


Given a source name filter the source list such that the supplied ID is a substring of the star ID (case insensitive).

    @stars = $catalog->filter_by_id("IRAS");

Would result in a catalog with all the stars with "IRAS" in their name. This is just a convenient alternative to filter_by_cb and is equivalent to

    @stars = $catalog->filter_by_cb(sub {$_[0]->id =~ /IRAS/i;});

A regular expression can be supplied explicitly using qr//:

    @stars = $catalog->filter_by_id(qr/^IRAS/i);

See popstarbyid for a similar method that returns stars that are an exact match to ID and removes them from the current list.


Retrieve all targets that are within the specified distance of the reference position.

    @selected = $catalog->filter_by_distance( $radius, $refpos );

The radius is in radians. The reference position defaults to the value returned by the reference method if none supplied.

API uncertainty:

    - Should the radius default to the get_radius() method?
    - Should this method take hash arguments?
    - Should there be a units argument? (radians, arcmin, arcsec, degrees)

Filter the star list using the given the supplied callback (reference to a subroutine). The callback should expect a star object and should return a boolean.

    @selected = $catalog->filter_by_cb(sub {$_[0]->id == "HLTau"});
    @selected = $catalog->filter_by_cb(sub {$_[0]->id =~ /^IRAS/;});


The following routines are available for sorting the star catalog. The sort applies to the current source list and not the original source list. This is the case even if no filters have been applied (ie the original unsorted catalog is always available).


Sort the catalog.


where mode can be one of




if a reference position is available. "az" and "el" require that the star coordinates have an associated telescope and that the reference time is correct.

If mode is a code reference, that will be passed to the sort routine directly. Note that the callback must expect $a and $b to be set.

The method force_ref_time is invoked prior to sorting unless the mode is "id". "name" is a synonym for "id".

Currently the unsorted option simply forces a reset_list since there is currently no tracking of the applied filters. It should be possible to step through the original list and the current filtered list and end up with a filtered but unsorted list. This is not implemented.

Pre-canned sorts are optimized because the values are precalculated prior to doing the sort rather than calculated each time through the sort.


Copyright (C) 2001-2002 University of Exeter. All Rights Reserved. Some modificiations Copyright (C) 2003 Particle Physics and Astronomy Research Council. All Rights Reserved.

This program was written as part of the eSTAR project and is free software; you can redistribute it and/or modify it under the terms of the GNU Public License.


Alasdair Allan <>, Tim Jenness <> Tim Lister <>