NAME

Astro::DSS::JPEG - Download color JPEG images from the Digitized Sky Survey

VERSION

Version 0.03

SYNOPSIS

    use Astro::DSS::JPEG;

    my $dss = Astro::DSS::JPEG->new();

    #get an object (Triangulum galaxy M33) by name at default 1000x1000,
    #getting coordinates and frame size automatically from SIMBAD
    my $image = $dss->get_image(target => 'M33');

    #Save an image directly to file manually specifying coordinates, frame of 
    #90x90 arcmin, 2048x2048 pixels
    $dss->get_image(
        ra           => '01 33 50.904',
        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');

DESCRIPTION

Astro::DSS::JPEG downloads JPEG images for any location in the sky from the Digitized Sky Survey (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 Astro::DSS module that would provide access to the slow FITS/GIF interface of the separate DSS1/DSS2 surveys.

Optionally, SIMBAD is used if you'd like to use an object name/id instead of coordinates.

CONSTRUCTOR METHODS

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 LWP::UserAgent, but you can pass your own with ua, while the URL to the STScI JPEG endpoint and the SIMBAD simple identifier query interface can be redefined (e.g. if they change in the future) from the above shown defaults.

METHODS

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 SIMBAD, or using RA & Dec when they are defined. If you pass a filename, the JPEG image will be saved to that and the function will return an HTTP::Response object, otherwise the image data will be returned as a response.

The parameters to pass:

• ra

  Right ascension, from 0-24h of angle. The option is flexible, it will accept a single decimal number - e.g. 2.5 or a string with hours, minutes, secs like '2 30 00' or '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 Astro::Coord::Precession::read_coordinates.

• dec

  Declination, from -90 to 90 degrees of angle. The option is flexible, it will accept a single decimal number - e.g. 54.5 or a string with degrees, minutes, secs like '+54 30 00' or '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 Astro::Coord::Precession::read_coordinates.

• epoch

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

• target

  Do a SIMBAD lookup to get the target by name (e.g. 'NGC598'). Will be disregarded if ra and dec are defined. If you have not defined an angular_size and SIMBAD has one defined, it will be used for the image request with an extra 50% for padding.

• 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 30 or '30,30' or even '30x30'). The aspect ratio will be overriden by pixel_size. If you care about framing, you should definitely define angular_size, as the default won't be appropriate for many targets and SIMBAD often does not have the info (or even has an inappropriate value). Also, large angular_size values can make the response slow (or even error out).

• 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 1000 or '1000,1000' or even '1000x1000'). Max possible is '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.

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.

AUTHOR

Dimitrios Kechagias, <dkechag at cpan.org>

BUGS

Please report any bugs or feature requests to bug-astro-dss-jpeg at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Astro-DSS-JPEG. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You could also submit issues or even pull requests to the github repo (see below).

GIT

https://github.com/dkechag/Astro-DSS-JPEG

ACKNOWLEDGEMENTS

The DSS images are downloaded using a public api of the Digitized Sky Survey provided by the Space Telescope Science Institute.

Targets by name/id are resolved using the SIMBAD Astronomical Database.

LICENSE AND COPYRIGHT

This software is copyright (c) 2020 by Dimitrios Kechagias.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

For the images you download with this module, please see the STScI site for the full copyright info.

cpanm Astro::DSS::JPEG

perl -MCPAN -e shell
install Astro::DSS::JPEG