view release on metacpan or  search on metacpan

Method/FINDOFF.pm  view on Meta::CPAN

use warnings::register;
use Carp;
use File::Temp qw/ tempfile /;
use Storable qw/ dclone /;

use Starlink::ADAM;
use Starlink::AMS::Init;
use Starlink::AMS::Task;
use Starlink::Config qw/ :override /;
use Starlink::EMS qw/ :sai get_facility_error /;

our $VERSION = '0.01';
our $DEBUG = 0;

# Cache the task.
our $TASK;

=head1 METHODS

=head2 General Methods

=over 4

=item B<correlate>

Cross-correlates two catalogues.

  ( $corrcat1, $corrcat2 ) = Astro::Correlate::Method::FINDOFF->correlate( catalog1 => $cat1,
                                                                           catalog2 => $cat2 );

This method takes two mandatory arguments, both C<Astro::Catalog> objects.
It returns two C<Astro::Catalog> objects containing C<Astro::Catalog::Star>
objects that matched spatially between the two input catalogues. The
first returned catalogue contains matched objects from the first input
catalogue, and ditto for the second. The C<Astro::Catalog::Star> objects
in the returned catalogues are not in the original order, nor do they have
the same IDs as in the input catalogues. A matched object has the same ID
in the two returned catalogues, allowing for further comparisons between
matched objects.

This method takes the following optional named arguments:

=item keeptemps - If this argument is set to true (1), then this
method will keep temporary files used in processing. Defaults to
false.

=item messages - If set to true (1), then this method will print
messages from the FINDOFF task during processing. Defaults to false.

=item temp - Set the directory to hold temporary files. If not set,
then a new temporary directory will be created using File::Temp.

=item timeout - Set the time in seconds to wait for the CCDPACK
monolith to time out. Defaults to 60 seconds.

=item verbose - If this argument is set to true (1), then this method will
print progress statements. Defaults to false.

This method uses the Starlink FINDOFF task, which is part of
CCDPACK. In order for this method to work it must be able to find
FINDOFF. It first looks in the directory pointed to by the CCDPACK_DIR
environment variable, then it looks in the Starlink binary files
directory pointed to by the Starlink::Config module, with C</ccdpack>
appended. If either of these fail, then this method will croak. See
the C<Starlink::Config> module for information on overriding the base
Starlink directory for non-standard installations.

=cut

sub correlate {
  my $class = shift;

# Grab the arguments, and make sure they're defined and are
# Astro::Catalog objects (the catalogues, at least).
  my %args = @_;
  my $inputcat1 = dclone( $args{'catalog1'} );
  my $inputcat2 = dclone( $args{'catalog2'} );

  if( ! defined( $inputcat1 ) ||
      ! UNIVERSAL::isa( $inputcat1, "Astro::Catalog" ) ) {
    croak "catalog1 parameter to correlate method must be defined and must be an Astro::Catalog object";
  }
  if( ! defined( $inputcat2 ) ||
      ! UNIVERSAL::isa( $inputcat2, "Astro::Catalog" ) ) {
    croak "catalog2 parameter to correlate method must be defined and must be an Astro::Catalog object";
  }

  # Make deep clones of the two input catalogues so we can modify IDs
  # and not trample those input catalogues.
  my $cat1 = dclone( $inputcat1 );
  my $cat2 = dclone( $inputcat2 );

  my $keeptemps = defined( $args{'keeptemps'} ) ? $args{'keeptemps'} : 0;
  my $temp;
  if( exists( $args{'temp'} ) && defined( $args{'temp'} ) ) {
    $temp = $args{'temp'};
  } else {
    $temp = tempdir( UNLINK => ! $keeptemps );
  }
  my $verbose = defined( $args{'verbose'} ) ? $args{'verbose'} : 0;
  my $messages = defined( $args{'messages'} ) ? $args{'messages'} : 0;
  my $timeout = defined( $args{'timeout'} ) ? $args{'timeout'} : 60;

# Try to find the FINDOFF binary. First, try the CCDPACK_DIR
# environment variable. If that doesn't find it, use
# Starlink::Config. If that doesn't work, croak.
  my $findoff_bin;
  if( defined( $ENV{'CCDPACK_DIR'} ) &&
      -d $ENV{'CCDPACK_DIR'} &&
      -e File::Spec->catfile( $ENV{'CCDPACK_DIR'}, "findoff" ) ) {
    $findoff_bin = File::Spec->catfile( $ENV{'CCDPACK_DIR'}, "findoff" );
  } elsif( -d File::Spec->catfile( $StarConfig{Star_Bin}, "ccdpack" ) &&
           -e File::Spec->catfile( $StarConfig{Star_Bin}, "ccdpack", "findoff" ) ) {
    $findoff_bin = File::Spec->catfile( $StarConfig{Star_Bin}, "ccdpack", "findoff" );
  } else {
    croak "Could not find FINDOFF binary.\n";
  }
  print "FINDOFF binary is in $findoff_bin\n" if $DEBUG;

# Get two temporary file names for catalog files.
  ( undef, my $catfile1 ) = tempfile( DIR => $temp );
  ( undef, my $catfile2 ) = tempfile( DIR => $temp );