panstamps ∞

Download stacked and/or warp image stamps from the STScI PanSTARRS image server via CL or Python API.

Documentation for panstamps is hosted by Read the Docs ( development version and master version). The code lives on github. Please report any issues you find here.

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.

Features ∞

How to cite panstamps ∞

If you use panstamps in your work, please cite using the following BibTeX entry:

@software{Young_panstamps,
    author = {Young, David R.},
    doi = {10.5281/zenodo.8037665},
    license = {GPL-3.0-only},
    title = ,
    url = {https://github.com/thespacedoctor/panstamps}
}

Installation ∞

The easiest way to install panstamps is to use pip (here we show the install inside of a conda environment):

conda create -n panstamps python=3.7 pip
conda activate panstamps
pip install panstamps

Or you can clone the github repo and install from a local version of the code:

git clone git@github.com:thespacedoctor/panstamps.git
cd panstamps
python setup.py install

To upgrade to the latest version of panstamps use the command:

pip install panstamps --upgrade

To check installation was successful run panstamps -v. This should return the version number of the install.

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

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 git@github.com:thespacedoctor/panstamps.git
cd panstamps
python setup.py develop

Pull requests are welcomed!

Initialisation ∞

Before using panstamps you need to use the init command to generate a user settings file. Running the following creates a yaml settings file in your home folder under ~/.config/panstamps/panstamps.yaml:

panstamps init

The file is initially populated with panstamps’s default settings which can be adjusted to your preference.

If at any point the user settings file becomes corrupted or you just want to start afresh, simply trash the panstamps.yaml file and rerun panstamps init.

Modifying the Settings ∞

Once created, open the settings file in any text editor and make any modifications needed.

Basic Python Setup ∞

If you plan to use panstamps in your own scripts you will first need to parse your settings file and set up logging etc. One quick way to do this is to use the fundamentals package to give you a logger, a settings dictionary and a database connection (if connection details given in settings file):

## SOME BASIC SETUP FOR LOGGING, SETTINGS ETC
from fundamentals import tools
from os.path import expanduser
home = expanduser("~")
settingsFile  = home + "/.config/panstamps/panstamps.yaml"
su = tools(
    arguments={"settingsFile": settingsFile},
    docString=__doc__,
)
arguments, settings, log, dbConn = su.setup()

Using Panstamps from the Command-Line ∞

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.

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 filter, 1 arcmin fits cutouts are downloaded:

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

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

As you can see we now have a larger cutout:

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.

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

Or grab the color image as well as/instead of the single filter images:

panstamps -FJc --width=4 --filters=gri --downloadFolder=/Users/Dave/Desktop/m81 stack 09:55:52.2 +69:40:47

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

panstamps -FJcig --width=4 --filters=gri --downloadFolder=/Users/Dave/Desktop/m81 stack 09:55:52.2 +69:40:47

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.

It’s also possible to request the closest warp image taken before or after a requested MJD by using the closest flag. 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

Using Panstamps within Python ∞

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()

for j in jpegPaths:

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

Todo List ∞

Todo

nice!

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/panstamps/checkouts/master/docs/source/_template_.md, line 1.)

Release Notes ∞

v0.6.5 - February 23, 2023

FIXED: fixed bug in parsing FITS urls. This was resulting in empty FITS files getting downloaded. (thanks to @fmannucci for reporting the issue.)

v0.6.4 - January 19, 2023

FIXED: a change to the JPEG endpoint URLs broke regex looking for images. JPEG images should be downloadable again. (thanks to @fforster for reporting the issue.)

v0.6.3 - January 6, 2023

refactor: moving from plpsipp1v.stsci.edu to ps1images.stsci.edu as end point to collect panstars images (thanks to Rick White for the pull-request)

v0.6.2 - May 11, 2022

FIXED doc fixes
UNFEATURE Removing Python 2 support

v0.6.1 - July 10, 2020

ENHANCEMENT Unit tests now added for command-line tools
FIXED Command-line tools now correctly parse arguments
FIXED Regex matching of warp image URLs updated to match filename changes made by STScI PanSTARRS image server

v0.6.0 - May 7, 2020

Now compatible with Python 3.*

API Reference ∞

Modules ∞

`panstamps.commonutils`	common tools used throughout package
`panstamps.image`	The worker class for the image module
`panstamps.commonutils.getpackagepath`	Get common file and folder paths for the host package
`panstamps.utKit`	Unit testing tools

Classes ∞

panstamps.downloader

Tools to download the panstarrs image stamps from STScI PanSTARRS image server

A-Z Index ∞

Modules

`panstamps.commonutils`	common tools used throughout package
`panstamps.image`	The worker class for the image module
`panstamps.commonutils.getpackagepath`	Get common file and folder paths for the host package
`panstamps.utKit`	Unit testing tools

Classes