view release on metacpan or  search on metacpan

lib/Astro/DSS/JPEG.pm  view on Meta::CPAN

        dec          => '+30 39 35.79',
        angular_size => 90,
        pixel_size   => 2048,
        filename     => $filename
    );

    #In one go, save Andromeda Galaxy to andromeda.jpg
    Astro::DSS::JPEG->new->get_image(target=>'Andromeda Galaxy', filename=>'andromeda.jpg');

=head1 DESCRIPTION

Astro::DSS::JPEG downloads JPEG images for any location in the sky from the L<Digitized Sky Survey (DSS)|https://archive.stsci.edu/dss/>.
It is meant to be a simple stand alone module to access a fast JPEG-only API that
provides color composites made from the blue and red DSS surveys.
In comparison, there is an old/not updated L<Astro::DSS> module that would provide
access to the slow FITS/GIF interface of the separate DSS1/DSS2 surveys.

Optionally, L<SIMBAD|http://simbad.u-strasbg.fr/simbad/> is used if you'd like to use
an object name/id instead of coordinates.

=head1 CONSTRUCTOR METHODS

=head2 C<new>

    my $dss = Astro::DSS::JPEG->new(
        dss_url    => 'http://gsss.stsci.edu/webservices/dssjpg/dss.svc/GetImage', # Optional
        simbad_url => 'http://simbad.u-strasbg.fr/simbad/sim-id',                  # Optional
        ua         => $ua                                                          # Optional
    );
  
All parameters are optional. The constructor by default creates an L<LWP::UserAgent>,
but you can pass your own with C<ua>, while the URL to the L<STScI|https://archive.stsci.edu/dss/copyright.html>
JPEG endpoint and the L<SIMBAD|http://simbad.u-strasbg.fr/simbad/> simple identifier query
interface can be redefined (e.g. if they change in the future) from the above shown defaults.

=head1 METHODS

=head2 C<get_image>

    my $res = $dss->get_image(
        target       => $target,            # Not used if RA, Dec provided
        ra           => $ra,                # Right Ascension (in hours of angle)
        dec          => $dec,               # Declination (in degrees of angle)
        epoch        => $epoch,             # Optional. Epoch for coordinates (otherwise J2000 assumed)
        angular_size => 30,                 # Optional. Frame angular size in arcmin
        pixel_size   => 1000,               # Optional. Frame size in pixels
        filename     => $filename           # Optional. Filename to save image to
    );

Fetches an image either resolving the name through L<SIMBAD|http://simbad.u-strasbg.fr/simbad/>,
or using RA & Dec when they are defined. If you pass a C<filename>, the JPEG image will
be saved to that and the function will return an L<HTTP::Response> object, otherwise the
image data will be returned as a response. 

The parameters to pass:

=over 4
 
=item * C<ra>

Right ascension, from 0-24h of angle. The option is flexible, it will accept a single
decimal number - e.g. C<2.5> or a string with hours, minutes, secs like C<'2 30 00'> or
C<'2h30m30s'> etc. Single/double quotes and single/double prime symbols are accepted
for denoting minute, second in place of a single space which also works.
Uses C<Astro::Coord::Precession::read_coordinates>.

=item * C<dec>

Declination, from -90 to 90 degrees of angle. The option is flexible, it will accept
a single decimal number - e.g. C<54.5> or a string with degrees, minutes, secs like
C<'+54 30 00'> or C<'54°30m30s'> etc. Single/double quotes and single/double prime symbols
are accepted for denoting minute, second in place of a single space which also works.
Uses C<Astro::Coord::Precession::read_coordinates>.

=item * C<epoch>

DSS uses J2000.0 coordinates, but you can enter custom epoch coordinates by specifying
it and it will be converted with L<Astro::Coord::Precession>.

=item * C<target>

Do a L<SIMBAD|http://simbad.u-strasbg.fr/simbad/> lookup to get the C<target> by name
(e.g. 'NGC598'). Will be disregarded if C<ra> and C<dec> are defined. If you have not
defined an C<angular_size> and L<SIMBAD|http://simbad.u-strasbg.fr/simbad/> has one
defined, it will be used for the image request with an extra 50% for padding.

=item * C<angular_size>

Define the frame angular size in arcminutes, either as a single number (square) or
a comma separated string for a rectangle. Default is 0.5 degrees (equivalent to passing
C<30> or C<'30,30'> or even C<'30x30'>). The aspect ratio will be overriden by C<pixel_size>.
If you care about framing, you should definitely define C<angular_size>, as the default
won't be appropriate for many targets and L<SIMBAD|http://simbad.u-strasbg.fr/simbad/> often
does not have the info (or even has an inappropriate value). Also, large C<angular_size>
values can make the response slow (or even error out).

=item * C<pixel_size>

Define the frame size in pixels, either as a single number (square) or a comma separated
string for a rectangle. Default is 1000 pixels (equivalent to passing C<1000> or
C<'1000,1000'> or even C<'1000x1000'>). Max possible is C<'4096,4096'> total size,
or 1 pixel / arcsecond resolution (e.g. 30*60 = 1800 pixels for 30 arcminutes), which
is the full resolution DSS plates were scanned at.

=back

=head1 NOTES

Some artifacts can be seen at the borders of separate "stripes" of the survey and
also the particular JPEG endpoint used sometimes can leave the corners as plain black
squares (depending on the selected frame size, as it is to do with the way it does
segmentation), so if you want to make sure you have a frame with no corner gaps,
request some more angular size than you want and crop. 

Note that the module test suite won't actually fetch data from either DSS or SIMBAD.
This is mainly to ensure it will not fail even if the DSS & SIMBAD endpoints change,
as you can still use the module by passing the updated urls to the constructor. It
also avoids unneeded strain to those free services.

=cut