1package Astro::Catalog::IO::FINDOFF;
2
3=head1 NAME
4
5Astro::Catalog::IO::FINDOFF - Catalogue I/O for Astro::Catalog for Starlink FINDOFF
6
7=head1 SYNOPSIS
8
9    $cat = Astro::Catalog::IO::FINDOFF->_read_catalog(\@lines);
10    $arrref = Astro::Catalog::IO::FINDOFF->_write_catalog($cat, %options);
11
12=head1 DESCRIPTION
13
14This class provides read and write methods for catalogues in the Starlink
15FINDOFF input and output file format. The methods are not public and should,
16in general only be called from the C<Astro::Catalog> C<write_catalog> and
17C<read_catalog> methods.
18
19=cut
20
21use warnings;
22use warnings::register;
23use Carp;
24use strict;
25
26use Astro::Catalog;
27use Astro::Catalog::Item;
28
29use base qw/Astro::Catalog::IO::ASCII/;
30
31our $VERSION = '4.36';
32our $DEBUG = 0;
33
34=head1 METHODS
35
36=head2 Private Methods
37
38=over 4
39
40=item B<_read_catalog>
41
42Parses the catalogue lines and returns a new C<Astro::Catalog>
43object containing the catalog entries.
44
45    $cat = Astro::Catalog::IO::FINDOFF->_read_catalog(\@lines, %options);
46
47There are currently no supported options.
48
49=cut
50
51sub _read_catalog {
52    my $class = shift;
53    my $lines = shift;
54
55    croak "Must supply catalogue contents as a reference to an array"
56        unless ref($lines) eq 'ARRAY';
57
58    # Create the Astro::Catalog object.
59    my $catalog = new Astro::Catalog();
60
61    # Chew up the lines. For position list files in FINDOFF, the first
62    # three columns are ID, X, and Y. Any columns after that could be
63    # anything, really, so put them in the Star's comment string.
64    my @lines = @$lines; # Dereference, make own copy.
65    for (@lines) {
66        my $line = $_;
67        next unless $line =~ /^\s*([\w\-.]+)\s+([\w\-.]+)\s+([\w\-.]+)(?:\s+(.+))*$/;
68        my $id = $1;
69        my $x = $2;
70        my $y = $3;
71        my $comment = $4;
72
73        # Create the Astro::Catalog::Item object.
74        my $star = new Astro::Catalog::Item(
75            ID => $id,
76            X => $x,
77            Y => $y,
78            Comment => $comment);
79
80        # And push the star onto the catalogue.
81        $catalog->pushstar($star);
82    }
83
84    # Set the catalogue's origin.
85    $catalog->origin('IO::FINDOFF');
86
87    # And return;
88    return $catalog;
89}
90
91=item B<_write_catalog>
92
93Create an output catalogue in the Starlink FINDOFF format and return
94the lines in an array.
95
96    $ref = Astro::Catalog::IO::FINDOFF->_write_catalog($catalog);
97
98The sole mandatory argument is an C<Astro::Catalog> object.
99
100As the Starlink FINDOFF is ID in column 1, X position in column 2,
101Y position in column 3, and miscellaneous information in the remaining
102columns that gets carried through to the output file, this method
103writes a new ID, X, and Y in the first three columns. A new ID is
104formed by removing any non-numbers from the original ID because
105FINDOFF cannot understand non-integer IDs. This ID is also written
106to the fourth column because FINDOFF trounces the original input
107ID when doing matching, and being able to have the original ID
108is a good thing.
109
110=cut
111
112sub _write_catalog {
113    my $class = shift;
114    my $catalog = shift;
115
116    croak "Must supply catalogue contents as a reference to an array"
117        unless UNIVERSAL::isa($catalog, "Astro::Catalog");
118
119    # Set up variables for output.
120    my @output;
121    my $output_line;
122
123    my $newid = 1;
124
125    # Loop through the stars.
126    foreach my $star ($catalog->stars) {
127        # We need at a bare minimum the X, Y, and ID.
128        next if (! defined($star->x) ||
129                ! defined($star->y) ||
130                ! defined($star->id));
131
132        (my $comment = $star->id) =~ s/[^\d]//g;
133
134        # Start off the output string.
135        $output_line = join(' ', $newid, $star->x, $star->y, $newid);
136
137        # And push this string to the output array.
138        push @output, $output_line;
139
140        $newid ++;
141    }
142
143    # All done looping through the stars, so return the array reference.
144    return \@output;
145}
146
1471;
148
149__END__
150
151=back
152
153=head1 SEE ALSO
154
155L<Astro::Catalog>, L<Astro::Catalog::IO::Simple>
156
157Starlink User Note 139 (http://www.starlink.ac.uk/star/docs/sun139.htx/sun139.html)
158
159=head1 COYPRIGHT
160
161Copyright (C) 2005 Particle Physics and Astronomy Research Council.
162All Rights Reserved.
163
164This program is free software; you can redistribute it and/or modify it
165under the terms of the GNU Public License.
166
167=head1 AUTHORS
168
169Brad Cavanagh E<lt>b.cavanagh@jach.hawaii.eduE<gt>
170
171=cut
172