SALT Finder Charts

Generate finder charts for the Southern African Large Telescope (SALT).

This package will change...

This is a preliminary and rudimentary version, and you should expect major changes in future versions.

Installation

The package can be installed with pip.

pip install salt_finder_charts

Usage

You can generate finder charts with the standard_finder_chart function. This returns a generator of binary streams containing the finder charts. For example, this is how you would generate finder charts for a longslit observation of an 18th magnitude target.

import astropy.units as u
from salt_finder_charts import standard_finder_charts
from salt_finder_charts.mode import Mode
from salt_finder_charts.output import OutputFormat

fcs = standard_finder_charts(
    bandpass="V",
    dec=-27.63792 * u.deg,
    max_magnitude=18,
    min_magnitude=18,
    mode=Mode.LONGSLIT,
    output_format=OutputFormat.PDF,
    position_angle=0 * u.deg,
    ra=78.6568723 * u.deg,
    slitwidth=2 * u.arcsec,
    title="Test Finding Chart"
)

Why a generator? Isn't there a single finder chart only? Usually that's true. However, in case of an asteroid you may get multiple finder charts, in particular if the considered time interval covers multiple nights.

Saving the generated finder charts to disk is fairly straightforward.

counter = 1
for fc in fcs:
    with open(f"FindingChart-{counter}.pdf", "wb") as f:
        f.write(fc.read())
        counter += 1

If you are certain there is only one finder chart, you could just use next() to get it.

fc = next(fcs)

Here is how you could view finder charts for an asteroid. Note that both the pytz and the Pillow library must have been installed, and that you have to hit enter for moving to the next finder chart.

from datetime import datetime
from PIL import Image

import pytz
import astropy.units as u
from salt_finder_charts import standard_finder_charts
from salt_finder_charts.mode import Mode
from salt_finder_charts.output import OutputFormat

utc = pytz.timezone("UTC")
start = utc.localize(datetime(2019, 6, 28, 11, 31, 0))
end = utc.localize(datetime(2019, 6, 29, 12, 31, 0))

for fc in standard_finder_charts(
    mode=Mode.IMAGING,
    horizons_id='54827',
    start_time=start,
    end_time=end,
    slitwidth=2 * u.arcsec,
    basic_annotations=False,
    output_format=OutputFormat.PNG
):
    image = Image.open(fc)
    image.show()
    input('Press enter to continue')
    image.close()

The standard_finder_charts function accepts the following arguments.

Which of these arguments are required depends on the combination of arguments used. Also, some arguments may be ignored when used with others. For example, the slit width won;t be used if the observing mode is imaging.

While normally you wouldn't have to use it, the salt_finder_charts package also offers a finder_charts function which lets you customise some aspects of the finder chart generation.

For example, you could create the same longslit observation finder charts as above with the following code.

import astropy.units as u
from salt_finder_charts import finder_charts
from salt_finder_charts.ephemerides import ConstantEphemerisService
from salt_finder_charts.image import SurveyImageService, Survey
from salt_finder_charts.mode import LongslitModeDetails
from salt_finder_charts.output import output_pdf
from salt_finder_charts.util import MagnitudeRange

magnitude_range = MagnitudeRange(bandpass="V", max_magnitude=18, min_magnitude=18)
ephemeris_service = ConstantEphemerisService(
    ra=78.6568723 * u.deg,
    dec=-27.63792 * u.deg,
    magnitude_range=magnitude_range
)
image_service = SurveyImageService(Survey.POSS2UKSTU_RED)
mode_details = LongslitModeDetails(slitwidth=2 * u.arcsec, pa=0 * u.deg)
fcs = finder_charts(
    ephemeris_service=ephemeris_service,
    image_service=image_service,
    mode_details=mode_details,
    output=output_pdf,
    title="test Finding Chart"
)

Like the standard_finder_charts function, finder_charts returns a generator of binary streams with the finder charts. It uses the following arguments.

Command-line interface for generating finder charts

For convenience, a command saltfc is provided, which you can run in a terminal. It saves the generated finding charts in a directory. The filename of the generated files consists of a basename (such as FinderChart) followed by a dash and a running number. The basename can be customised with a command line option. Existing files are replaced without warning,

For example, you can generate finder charts for an asteroid by running the following command in a terminal.

saltfc \
    --output-dir /tmp \
    --basename "Asteroid_54827" \
    --mode imaging \
    --horizons-id 54827 \
    --start-time "2019-06-28 11:31:00" \
    --end-time "2019-06-29 12:31:00" \
    --output-format PDF

The command line options for saltfc are essentially the same as the arguments for the standard_finder_charts function, plus options for customising the file base name and setting the output directory.

Both the start and end time use the format yyyy-mm-dd hh:mm:ss. For example, valid values are 2019-01-25 9:45:16' or 2020-01-02 12:00:00.

Command interface for calculating position angles

A suitable position angle for a target can be calculated with the pa command. It tries to find a star in an annulus around the target with a magnitude in a given magnitude range. The stsr must have a given minimum separation from its neighbouring stars.

The radii, magnitudes and minimum separation all have default values, and usually you should not have to specify them. Hence a typical call of pa looks as follows./

pa --ra 217.524 --dec -23.97611

Here is a list of the available arguments for pa.