Quickstart

Let’s imagine you’re impatient, and all you want to do is make a pretty movie or two. Here’s a good place to start. Odds are, you have a collection of .fits files somewhere, and you’d like to display them as a movie. To simulate your situation, let’s make a directory full of files.

from playground.cartoons import create_directory_of_fits
create_directory_of_fits('some-directory')

If we look in the some-directory directory, we see it contains four directories, each of which contain some images.

!ls some-directory/*

some-directory/cam1:
cam1-0000.fits cam1-0002.fits cam1-0004.fits cam1-0006.fits cam1-0008.fits
cam1-0001.fits cam1-0003.fits cam1-0005.fits cam1-0007.fits cam1-0009.fits

some-directory/cam2:
cam2-0000.fits cam2-0002.fits cam2-0004.fits cam2-0006.fits cam2-0008.fits
cam2-0001.fits cam2-0003.fits cam2-0005.fits cam2-0007.fits cam2-0009.fits

some-directory/cam3:
cam3-0000.fits cam3-0002.fits cam3-0004.fits cam3-0006.fits cam3-0008.fits
cam3-0001.fits cam3-0003.fits cam3-0005.fits cam3-0007.fits cam3-0009.fits

some-directory/cam4:
cam4-0000.fits cam4-0002.fits cam4-0004.fits cam4-0006.fits cam4-0008.fits
cam4-0001.fits cam4-0003.fits cam4-0005.fits cam4-0007.fits cam4-0009.fits

Basic Animations

Now, starting with these FITS, we can use the following commands to visualize those images.

from playground.tv import illustratefits, glob

i = illustratefits('some-directory/cam1/*.fits')
i.animate('_static/a-snazzy-little-movie.mp4')

Neat! That makes us a little animation!

The illustratefits function will make an animation out of all the files that matches the file pattern (with glob). It will try to find times inside the headers of those images, but if it doesn’t, it will simply order images by filename.

If you want, you can explicitly create a list of files to include. For example, you could feed in the same files, but in reverse, as follows.

files = glob.glob('some-directory/cam1/*.fits')[::-1]
i = illustratefits(files, title="now it's backwards!")
i.animate('_static/backwards-snazzy-little-movie.mp4', fps=3, dpi=200)

Note that we’ve also changed a few other things in here too. We added a title to the illustration, and we changed the frame per second (fps) and the dots per inch (dpi) to use when writing the animation.

Animating Multiple Cameras at Once

But what if you want to display more than one camera at the same time? The illustratefits will try to split out different cameras by looking for a string like cam1 or cam2 (etc...) in the FITS filenames. If it doesn’t find these, it will revert back to assuming everything is in a single camera.

i = illustratefits('some-directory/cam*/*.fits')
i.animate('_static/a-snazzy-fourcamera-movie.mp4', dpi=50)

Magnifying Part of the Frame

What if I want to zoom in on a particular region of an image? I can specify the zoom I would like via the zoomposition and zoomsize keywords, indicating the (x,y)=(col,row) position of the center of the zoom box, and the

i = illustratefits('some-directory/cam1/*.fits', zoomposition=(30, 50), zoomsize=(42, 14))
i.animate('_static/zoom-movies-are-snazzy-too.mp4', dpi=50)

Basic Image Processing

Sometimes, you might want to apply some processing to the images before displaying them. Several simple processes are defined via the processingsteps keyword, which must contain a list (something inside []) of steps to be applied. The current options are subtractmedian and subtractmean. Be careful trying to use subtractmedian on large datasets – it requires reading the entire dataset into memory at once.

i = illustratefits('some-directory/cam*/*.fits', processingsteps=['subtractmedian'])
i.animate('_static/median-subtraction-reveals-sazzy-structures.mp4', dpi=50)

Static Illustrations

We can also simply plot a single time, and save that as a PDF.

i = illustratefits('some-directory/cam*/*0001.fits')
i.plot()
i.savefig('_static/a-snazzy-static-plot.png')

That’s about it for the basic one-liner commands. If you want to do something more complicated, it will probably help to read on a bit more about the principle of how TESS Viewer illustrations are structured.

Bug Reports

You will probably encounter bugs as you play with this yourself. If so, please do not hesitate to contact Zach Berta-Thompson, or leave an issue on the gitlab repository.