Panstamps Documentation Release V0.5.3

panstamps Documentation Release v0.5.3

Dave Young

2020

Getting Started

1 Installation 3 1.1 Troubleshooting on Mac OSX...... 3 1.2 Development...... 3 1.2.1 Sublime Snippets...... 4 1.3 Issues...... 4

2 Command-Line Usage 5

3 Documentation 7

4 Command-Line Tutorial 9 4.1 Command-Line...... 9 4.1.1 JPEGS...... 12 4.1.2 Temporal Constraints (Useful for Moving Objects)...... 17 4.2 Importing to Your Own Python Script...... 18

5 Installation 19 5.1 Troubleshooting on Mac OSX...... 19 5.2 Development...... 19 5.2.1 Sublime Snippets...... 20 5.3 Issues...... 20

6 Command-Line Usage 21

7 Documentation 23

8 Command-Line Tutorial 25 8.1 Command-Line...... 25 8.1.1 JPEGS...... 28 8.1.2 Temporal Constraints (Useful for Moving Objects)...... 33 8.2 Importing to Your Own Python Script...... 34 8.2.1 Subpackages...... 35 8.2.1.1 panstamps.commonutils (subpackage)...... 35 8.2.1.2 panstamps.image (subpackage)...... 35 8.2.2 Classes...... 35 8.2.2.1 panstamps.downloader (class)...... 35 8.2.2.2 panstamps.image.image (class)...... 36

i 8.3 Indexes...... 38 8.4 Todo...... 38

Python Module Index 39

Index 41

ii panstamps Documentation, Release v0.5.3

A python package and command-line tools to download stacked and/or warp image stamps from the STScI PanSTARRS image server.

Note: If working with warped PS1 images then you need to work off a machine that has an IP address whitelisted by the Pan-STARRS1 data archive, otherwise only stacked images will be available to you. Also w-band images are not (yet) accessible from the data archive.

Here’s a summary of what’s included in the python package: Classes

panstamps.downloader Tools to download the panstarrs image stamps from STScI PanSTARRS image server panstamps.image.image The worker class for the image module

Functions

Getting Started 1 panstamps Documentation, Release v0.5.3

2 Getting Started CHAPTER 1

Installation

The easiest way to install panstamps is to use pip: pip install panstamps

Or you can clone the github repo and install from a local version of the code: git clone [email protected]:thespacedoctor/panstamps.git cd panstamps python setup.py install

To upgrade to the latest version of panstamps use the command: pip install panstamps--upgrade

1.1 Troubleshooting on Mac OSX panstamps uses pillow (a fork of the Python Imaging Library) which requires some external libraries. If you have issues running panstamps on OSX, try installing Homebrew and running: brew install libtiff libjpeg webp little-cms2

1.2 Development

If you want to tinker with the code, then install in development mode. This means you can modify the code from your cloned repo: git clone [email protected]:thespacedoctor/panstamps.git cd panstamps python setup.py develop

3 panstamps Documentation, Release v0.5.3

Pull requests are welcomed!

1.2.1 Sublime Snippets

If you use Sublime Text as your code editor, and you’re planning to develop your own python code with panstamps, you might ﬁnd my Sublime Snippets useful.

1.3 Issues

Please report any issues here.

4 Chapter 1. Installation CHAPTER 2

Command-Line Usage

Documentation for panstamps can be found here: http://panstamps.readthedocs.org/en/

˓→stable

Usage: panstamps [options] [--width=] [--filters=] [--settings=

˓→] [--downloadFolder=] (warp|stack) [

˓→] panstamps [options] --closest= [--width=] [--filters=

˓→] [--settings=] [--downloadFolder=]

˓→

-h, --help show this help message -f, --fits download fits (default on) -F, --nofits don't download fits (default off) -j, --jpeg download jepg (default off) -J, --nojpeg don't download jepg (default on) -c, --color download color jepg (default off) -C, --nocolor don't download color jepg (default on) -a, --annotate annotate jpeg (default true) -A, --noannotate don't annotate jpeg (default false) -t, --transient add a small red circle at transient

˓→location (default false) -T, --notransient don't add a small red circle at transient

˓→location (default true) -g, --greyscale convert jpeg to greyscale (default false) -G, --nogreyscale don't convert jpeg to greyscale (default

˓→true) -i, --invert invert jpeg colors (default false) -I, --noinvert don't invert jpeg colors (default true) --width= width of image in arcsec (default 1) --filters= filter set to download and use for color

˓→image (default gri) --downloadFolder= path to the download folder, relative or

˓→absolute (folder created where command is run if not set) (continues on next page)

5 panstamps Documentation, Release v0.5.3

(continued from previous page) --settings= the settings file --closest= return the warp closest in time to the

˓→given mjd. If you want to set a strict time window then pass in a positive or

˓→negative time in sec (before | after | secs)

ra right-ascension in sexagesimal or decimal

˓→degrees dec declination in sexagesimal or decimal

˓→degrees mjdStart the start of the time-window within which

˓→to select images mjdEnd the end of the time-window within which

˓→to select images mjd report the warp closest in time to this

˓→mjd

6 Chapter 2. Command-Line Usage CHAPTER 3

Documentation

Documentation for panstamps is hosted by Read the Docs (last stable version and latest version).

7 panstamps Documentation, Release v0.5.3

8 Chapter 3. Documentation CHAPTER 4

Command-Line Tutorial

There are 2 ways to use panstamps, either via the command-line or import it into your own python code and use it from there.

4.1 Command-Line

Full usage options can be found by typing: panstamps -h

Here I’ll run through the basics. By default the command will only download the fits files for the location given. To download the stack fits cutouts for M82 run the command: panstamps stack 09:55:52.2 +69:40:47

By default the gri ﬁlter, 1 arcmin ﬁts cutouts are downloaded:

9 panstamps Documentation, Release v0.5.3

10 Chapter 4. Command-Line Tutorial panstamps Documentation, Release v0.5.3

To increase the image width and download all ﬁlters, run the command:

4.1. Command-Line 11 panstamps Documentation, Release v0.5.3

panstamps --width=4 --filters=griyz stack 09:55:52.2 +69:40:47

As you can see we now have a larger cutout:

4.1.1 JPEGS

To download the jpegs, and not the fits files rerun the command with the correct flags set. We’ll also use the --downloadFolder option to assign the download directory.

12 Chapter 4. Command-Line Tutorial panstamps Documentation, Release v0.5.3

panstamps -Fj --width=4 --filters=gri --downloadFolder=/Users/Dave/Desktop/m81 stack

˓→09:55:52.2 +69:40:47

This downloads the jpegs and adds some useful annotation, which can be switched off if required.

Sometimes it maybe useful to add a transient marker at the centre of the image: panstamps -FjAt --width=4 --filters=gri --downloadFolder=/Users/Dave/Desktop/m81

˓→stack 09:55:52.2 +69:40:47

4.1. Command-Line 13 panstamps Documentation, Release v0.5.3

Or grab the color image as well as/instead of the single ﬁlter images: panstamps -FJc --width=4 --filters=gri --downloadFolder=/Users/Dave/Desktop/m81 stack

˓→09:55:52.2 +69:40:47

14 Chapter 4. Command-Line Tutorial panstamps Documentation, Release v0.5.3

Note the code will try its best to choose a colour for the annotation lines and text to make them contrast well against the background image. Finally you can invert the image colors or convert the image to greyscale: panstamps -FJci --width=4 --filters=gri --downloadFolder=/Users/Dave/Desktop/m81

˓→stack 09:55:52.2 +69:40:47

4.1. Command-Line 15 panstamps Documentation, Release v0.5.3

panstamps -FJcig --width=4 --filters=gri --downloadFolder=/Users/Dave/Desktop/m81

˓→stack 09:55:52.2 +69:40:47

16 Chapter 4. Command-Line Tutorial panstamps Documentation, Release v0.5.3

4.1.2 Temporal Constraints (Useful for Moving Objects)

For moving objects, alongside spatially filtering the panstarrs images, we also require a temporal filter. We need to be able to request images at a sky-position that were taken within a given time range. With panstamps we have the option of passing a time-window to filter the images by via the mjdStart and mjdEnd variables: For example I can run: panstamps -Fj --width=4 --filters=gri --downloadFolder=~/Desktop/movers warp 189.

˓→1960991 28.2374845 55246.63 55246.64 to only return the 2 images I want within the temporal window at the location in the sky.

4.1. Command-Line 17 panstamps Documentation, Release v0.5.3

It’s also possible to request the closest warp image taken before or after a requested MJD by using the closest ﬂag. For example, to request the closest r-band warp taken before MJD=‘55246.64‘ for the location above, run the command: panstamps -Fj --closest=before --width=4 --filters=gri --downloadFolder=~/Desktop/

˓→movers 189.1960991 28.2374845 55246.64

To request the closest warp taken after the given MJD then use --closest=after. Oftentimes it’s useful to download the closest warp within a given time-window, e.g. closest warp in time of the requested MJD taken up to 3 mins before. To do so pass in a postive or negative integer to represent the time-window in seconds, like so: panstamps -Fj --closest=-120 --width=4 --filters=gri --downloadFolder=~/Desktop/

˓→movers 189.1960991 28.2374845 55246.64

4.2 Importing to Your Own Python Script

To use panstamps within your own scripts please read the full documentation. But for those of you that can’t wait, this snippet should give you the basics: from panstamps.downloader import downloader from panstamps.image import image fitsPaths, jpegPaths, colorPath= downloader( log=log, settings=False, downloadDirectory=False, fits=False, jpeg=True, arcsecSize=600, filterSet='gri', color=True, singleFilters=True, ra="70.60271", dec="-21.72433", imageType="stack", # warp | stack mjdStart=False, mjdEnd=False, window=False ).get() forj in jpegPaths:

myimage= image( log=log, settings=False, imagePath=j arcsecSize=120, crosshairs=True, transient=False, scale=True, invert=False, greyscale=False ).get()

18 Chapter 4. Command-Line Tutorial CHAPTER 5

Installation

The easiest way to install panstamps is to use pip: pip install panstamps

Or you can clone the github repo and install from a local version of the code: git clone [email protected]:thespacedoctor/panstamps.git cd panstamps python setup.py install

To upgrade to the latest version of panstamps use the command: pip install panstamps--upgrade

5.1 Troubleshooting on Mac OSX panstamps uses pillow (a fork of the Python Imaging Library) which requires some external libraries. If you have issues running panstamps on OSX, try installing Homebrew and running: brew install libtiff libjpeg webp little-cms2

5.2 Development

19 panstamps Documentation, Release v0.5.3

Pull requests are welcomed!

5.2.1 Sublime Snippets

If you use Sublime Text as your code editor, and you’re planning to develop your own python code with panstamps, you might ﬁnd my Sublime Snippets useful.

5.3 Issues

Please report any issues here.

20 Chapter 5. Installation CHAPTER 6

Command-Line Usage

Documentation for panstamps can be found here: http://panstamps.readthedocs.org/en/

˓→stable

Usage: panstamps [options] [--width=] [--filters=] [--settings=

˓→] [--downloadFolder=] (warp|stack) [

˓→] panstamps [options] --closest= [--width=] [--filters=

˓→] [--settings=] [--downloadFolder=]

˓→

˓→location (default false) -T, --notransient don't add a small red circle at transient

˓→location (default true) -g, --greyscale convert jpeg to greyscale (default false) -G, --nogreyscale don't convert jpeg to greyscale (default

˓→image (default gri) --downloadFolder= path to the download folder, relative or

˓→absolute (folder created where command is run if not set) (continues on next page)

21 panstamps Documentation, Release v0.5.3

(continued from previous page) --settings= the settings file --closest= return the warp closest in time to the

˓→given mjd. If you want to set a strict time window then pass in a positive or

˓→negative time in sec (before | after | secs)

ra right-ascension in sexagesimal or decimal

˓→degrees dec declination in sexagesimal or decimal

˓→degrees mjdStart the start of the time-window within which

˓→to select images mjdEnd the end of the time-window within which

˓→to select images mjd report the warp closest in time to this

˓→mjd

22 Chapter 6. Command-Line Usage CHAPTER 7

Documentation

Documentation for panstamps is hosted by Read the Docs (last stable version and latest version).

23 panstamps Documentation, Release v0.5.3

24 Chapter 7. Documentation CHAPTER 8

Command-Line Tutorial

There are 2 ways to use panstamps, either via the command-line or import it into your own python code and use it from there.

8.1 Command-Line

Full usage options can be found by typing: panstamps -h

By default the gri ﬁlter, 1 arcmin ﬁts cutouts are downloaded:

25 panstamps Documentation, Release v0.5.3

26 Chapter 8. Command-Line Tutorial panstamps Documentation, Release v0.5.3

To increase the image width and download all ﬁlters, run the command:

8.1. Command-Line 27 panstamps Documentation, Release v0.5.3

panstamps --width=4 --filters=griyz stack 09:55:52.2 +69:40:47

As you can see we now have a larger cutout:

8.1.1 JPEGS

To download the jpegs, and not the fits files rerun the command with the correct flags set. We’ll also use the --downloadFolder option to assign the download directory.

28 Chapter 8. Command-Line Tutorial panstamps Documentation, Release v0.5.3

panstamps -Fj --width=4 --filters=gri --downloadFolder=/Users/Dave/Desktop/m81 stack

˓→09:55:52.2 +69:40:47

This downloads the jpegs and adds some useful annotation, which can be switched off if required.

Sometimes it maybe useful to add a transient marker at the centre of the image: panstamps -FjAt --width=4 --filters=gri --downloadFolder=/Users/Dave/Desktop/m81

˓→stack 09:55:52.2 +69:40:47

8.1. Command-Line 29 panstamps Documentation, Release v0.5.3

Or grab the color image as well as/instead of the single ﬁlter images: panstamps -FJc --width=4 --filters=gri --downloadFolder=/Users/Dave/Desktop/m81 stack

˓→09:55:52.2 +69:40:47

30 Chapter 8. Command-Line Tutorial panstamps Documentation, Release v0.5.3

˓→stack 09:55:52.2 +69:40:47

8.1. Command-Line 31 panstamps Documentation, Release v0.5.3

panstamps -FJcig --width=4 --filters=gri --downloadFolder=/Users/Dave/Desktop/m81

˓→stack 09:55:52.2 +69:40:47

32 Chapter 8. Command-Line Tutorial panstamps Documentation, Release v0.5.3

8.1.2 Temporal Constraints (Useful for Moving Objects)

˓→1960991 28.2374845 55246.63 55246.64 to only return the 2 images I want within the temporal window at the location in the sky.

8.1. Command-Line 33 panstamps Documentation, Release v0.5.3

˓→movers 189.1960991 28.2374845 55246.64

8.2 Importing to Your Own Python Script

myimage= image( log=log, settings=False, imagePath=j arcsecSize=120, crosshairs=True, transient=False, scale=True, invert=False, greyscale=False ).get()

34 Chapter 8. Command-Line Tutorial panstamps Documentation, Release v0.5.3

8.2.1 Subpackages

panstamps.commonutils common tools used throughout package panstamps.image The worker class for the image module

8.2.1.1 panstamps.commonutils (subpackage) common tools used throughout package

8.2.1.2 panstamps.image (subpackage)

8.2.2 Classes

panstamps.downloader Tools to download the panstarrs image stamps from STScI PanSTARRS image server panstamps.image.image The worker class for the image module

8.2.2.1 panstamps.downloader (class) class panstamps.downloader(log, downloadDirectory=False, settings=False, fits=True, jpeg=False, arcsecSize=60, filterSet=’gri’, color=True, singleFilters=True, ra=False, dec=False, imageType=’stack’, mjdStart=False, mj- dEnd=False, window=False) Tools to download the panstarrs image stamps from STScI PanSTARRS image server Key Arguments: • log – logger • settings – the settings dictionary • downloadDirectory – the path to where you want to download the images to. Downlaods to path command is run from by default. • fits – download the fits files? Default True • jpeg – download the jpeg files? Default False • arcsecSize – the size of the image stamps to download (1 arcsec == 4 pixels). Default 60 • filterSet – the filter set used to create color and/or download as individual stamps. Default gri • color – download the color jpeg? Default True • singleFilters – download the single filter stmaps? Default False • ra – ra in decimal degrees. • dec – dec in decimal degrees. • imageType – warp or stacked images? Default stack • mjdStart – the start of a time-window within which the images required are taken. Default False (everything) • mjdEnd – the end of a time-window within which the images required are taken. Default False (everything) Usage: The following will return 3 lists of paths to local fits, jpeg and color-jpeg files:

8.2. Importing to Your Own Python Script 35 panstamps Documentation, Release v0.5.3

from panstamps.downloader import downloader fitsPaths, jpegPaths, colorPath= downloader( log=log, settings=False, fits=False, jpeg=True, arcsecSize=600, filterSet='gri', color=True, singleFilters=True, ra="70.60271", dec="-21.72433", imageType="stack", mjdStart=False, mjdEnd=False, window=False ).get()

__init__(log, downloadDirectory=False, settings=False, ﬁts=True, jpeg=False, arcsecSize=60, ﬁlter- Set=’gri’, color=True, singleFilters=True, ra=False, dec=False, imageType=’stack’, mjd- Start=False, mjdEnd=False, window=False)

Methods

__init__(log[, downloadDirectory, settings, . . . ]) get() download the requested jpegs and ﬁts ﬁles get_html_content() Build the URL for the stamp request and extract the HTML content parse_html_for_image_urls_and_metadataparse(content) html for image urls and metadata

8.2.2.2 panstamps.image.image (class) class panstamps.image.image(log, imagePath, arcsecSize, settings=False, crosshairs=True, transient=False, scale=True, invert=False, greyscale=False, colorIm- age=False) The worker class for the image module Key Arguments: • log – logger • settings – the settings dictionary • imagePath – path to the image to manipulate • arcsecSize – the size of the image stamps to download (1 arcsec == 4 pixels). • crosshairs – add crosshairs to the image?. Default True • transient – add a small transient marker at the centre of the image. Default False • scale – add scale bar and orientation indicator to the image. Default True • invert – invert the colours of the image. Default False • greyscale – convert the image to greyscale. Default False • colorImage – is the input image a color image, Default **False*. Note, also assumes a color image if ‘color’ in ﬁlename

36 Chapter 8. Command-Line Tutorial panstamps Documentation, Release v0.5.3

Usage:

from panstamps.image import image myimage= image( log=log, settings=False, imagePath="70.60271m21.72433/color_igr_ra70.602710_dec-21.724330_

˓→arcsec120_skycell0812.050.jpeg", arcsecSize=120, crosshairs=True, transient=False, scale=True, invert=False, greyscale=False, colorImage=True ).get()

Here’s the resulting image from this code:

__init__(log, imagePath, arcsecSize, settings=False, crosshairs=True, transient=False, scale=True, invert=False, greyscale=False, colorImage=False)

8.2. Importing to Your Own Python Script 37 panstamps Documentation, Release v0.5.3

Methods

__init__(log, imagePath, arcsecSize[, . . . ]) get() annotate the PS1 image

8.3 Indexes

• Module Index • Full Index

8.4 Todo

• Todolist

38 Chapter 8. Command-Line Tutorial Python Module Index

c panstamps.commonutils, 35 i panstamps.image, 35

39 panstamps Documentation, Release v0.5.3

40 Python Module Index Index

Symbols __init__() (panstamps.downloader method), 36 __init__() (panstamps.image.image method), 37 D downloader (class in panstamps), 35 I image (class in panstamps.image), 36 P panstamps.commonutils (module), 35 panstamps.image (module), 35