Contents:

• Introduction
  
• List of features.
• Currently known bugs, problems, and workarounds.
• Known issues.
• Disclaimer.
• Comments, complaints, suggestions?

Introduction.

Back when I started using IDL a lot, around 1998, one thing I wanted which didn't really exist at the time was an interactive image-display tool optimized for viewing astronomical CCD images.  There are a lot of nice image viewing programs out there, like SAOimage , which are usually designed to work with IRAF or as stand-alone applications (see here for a list of other image viewers), but for working in IDL it would be far easier to have a display routine written as an IDL procedure.  In order to learn how to use IDL widgets, I started writing an image viewer which would do some of the things I wanted.   It seemed like something that would be useful to other IDL users, so I made it available here.  The program is written entirely in IDL.  It's very easy to use within an IDL session and it's also very simple to add new routines, buttons, menus, or whatever.   It looks a lot like SAOimage or DS9, so if you're used to using those programs, then you'll probably get used to ATV quickly.  

For detailed instructions on how to use atv, see the instructions page .

ATV version 3.0 requires IDL version 8.0 or greater.  If you are still using an IDL 7.x version, you can still use the older 2.3 version of ATV that's posted on this site, but you will likely find incompatibilities and funny behavior related to recent updates to the IDL Astronomy User's Library.  Upgrading to IDL 8 is highly recommended.

One nice thing about ATV is that you, the user, can easily add new features or link your existing IDL programs to ATV.  For example, you can easily define a keyboard shortcut that will pass the current cursor position in data coordinates to an external IDL routine.  Also, all of the ATV internal variables are stored in common blocks, so you can have another program access the ATV variables by declaring the ATV common blocks in your program.

I have been told that as of late 2015, ATV will work with GDL, if GDL is compiled with the wxWidgets library. I haven't tried this myself, but this may be useful as an option for those who don't have an IDL license.

What atv can do for you.

A quick list of ATV's main features:

• Display of 2-d images with a variety of scaling, color map, color stretch, zoom, and rotation options
• World coordinate system information is displayed if available
  
• Labeling and overplots to annotate images
  
• Image output in a variety of formats
• Display of line plots, surface plots, and histograms of data regions
• Quick photometry and image statistics
• Simple spectral extractions
  
• Image blinking
• Display of image cubes including ALMA cubes
  

In comparison with some other image viewing applications, ATV has some nice features:

• It's very easy to change the image scaling parameters such as the minimum and maximum pixel values that get mapped into the color table
• The asinh scaling works really well for most images
  
• The autoscaling routine is done by estimating the sky value and sky sigma, so the default autoscaling parameters work pretty well- this means you can often read an image into ATV and it will just show up pretty much the way you want to see it, without having to do a lot of mucking around with the image scaling parameters
• While ATV is not as feature-rich as DS9, ATV's menus are a lot simpler and easier to use
• One-click photometry and spectral extractions can be handy for quick-look analysis
  

Since I don't have all that much time to debug and test ATV, it's likely that there are some bugs hidden in the program which I haven't discovered yet.  If you find a bug, send me an email and tell me what went wrong, and please be as specific as possible about what you were doing and what IDL version and platform you're running.  Currently known bugs in ATV or general IDL issues that affect ATV are listed below.

August 2020: Problems reading FPACK-compressed FITS files? ATV can read in FPACK-compressed images, if you have the funpack routine installed as part of a cfitsio installation. Make sure that you've installed the funpack executable in a directory that's part of your PATH so that IDL can find it.  If the unix/linux command "which funpack" returns a valid path to the executable, then IDL should be able to use it.

One problem that can come up is that the IDL Astronomy User's Library FITS-reading routines will automatically recognize a FITS file as FPACK-compressed if it has the .fz suffix. However, if the file is missing the .fz suffix in the filename, there isn't a simple way for IDL to automatically detect whether the file is FPACK-compressed or not. If you have an FPACK-compressed image whose suffix is just ".fits", then ATV won't be able to read it directly. I'd like to find a way to fix that, but for now the quickest workaround is just to rename the file to add the .fz suffix. That is, change the filename from "image.fits" to "image.fits.fz" and then it should read in properly. This can be an issue for images coming from a variety of sources, like the Subaru HSC public data release for example. If you have a compressed image that you can read in with DS9, but ATV won't read the image, this is what might be happening, and it's just that ATV doesn't know how to automatically recognize the image compression without the ".fz" suffix.

November 2016: Fix for MacOS XQuartz Widget Problem:  In the most recent update to XQuartz (version 2.7.10 or 2.7.11), something happened that causes IDL widget programs to crash IDL completely. The symptom of this problem is that if you try to run ATV or xloadct or other widget programs, you'll get an error message saying "Error: attempt to add non-widget child 'dsm' to parent 'idl' which supports only widgets", and your IDL session will crash.  The fix for this problem is explained here:
http://prod.lists.apple.com/archives/x11-users/2016/Oct/msg00030.html

After that, widgets seem to work fine again. Thanks to Phil Appleton for diagnosing this problem and pointing out the solution.

Other bugs/issues:

• In the current version there may be problems with saving and loading region files- I'll work on this as time permits.  Other problems with circle and box regions coming out in the wrong locations have been fixed, and you need to have current versions of the GSFC and Coyote libraries in order to get region overplots to work.

If you are having trouble getting ATV to work, here are the first things to check:

• You need IDL 8.0 or greater. It won't work with earlier versions.
• Make sure you have up to date versions of the IDL astronomy user's library and coyote graphics library.
• If you have the SDSS idlutils package in your IDL path, that is likely to cause some compatibility issues. Make sure to remove the ancient version of ATV that's distributed with idlutils!
  
• If you still can't get ATV to compile or work, feel free to send me an email. Please let me know the operating system, IDL version, and ATV version that you're using, and send a log of the error messages that you are getting and a description of what happened.
  

Known issues.

These are peculiarities of the program that can't really be classified as bugs.  Some have to do with inherent limitations of IDL widgets, and others have to do with how IDL behaves differently under different platforms.

• If you're using a system that has fewer than 3 mouse buttons, you may not be able to access all features of the program.  I've attempted to make many features for buttons 2 and 3 accessible in other ways (i.e. keyboard shortcuts), but some features require having 3 buttons.  For example, if you've only got 1 button, then you can only use 1 blink image.  If you are using a Linux machine that has 2 buttons and emulates a 3-button mouse by holding both buttons down, then blinking may not do exactly what you expect for the second and third "blink" images.
• The way IDL widgets work, the best thing to do is to define the widgets using the default fontset, rather than to specify a particular font, since different platforms may have different fonts installed.  The result is that the layout of the buttons and windows in the ATV window will depend somewhat on your platform, window manager, and default font size.  This snapshot gives you an idea of what the ATV window is intended to look like.  If your window manager uses really big fonts, you can just resize the ATV window to make things fit better.
• The inner workings of ATV are based on IDL event handlers.  If you have another IDL routine running from the IDL command line prompt, or from a blocking or modal widget, then the ATV event subroutines may not be accessible until the other routine finishes what it's doing.  For example, if your main IDL prompt is waiting for input at a "read" statement, or something like that, then ATV won't be usable until after that read statement takes its input.  There's nothing that I can do about this; it's just how IDL widgets work.  So if your ATV window appears to freeze, the most common reason is that there's another IDL program running which is blocking the ATV event routines from executing.  ATV will also freeze if you have another IDL program that hits an execution error or a "stop" statement.
  
• Fractional pixels are handled in a very simple way, which forces the lower left corner of the viewport to display a complete pixel.  You might notice this when displaying an image with a very high zoom factor.  This is a direct consequence of my own laziness.  Fractional pixels might be handled better in a future version, but this isn't really a high priority.
• In some window managers, window resizing can be a little finicky.  I've gotten it to work pretty well in Linux with the metacity window manager, and in Mac OS X.   If you resize the main window and things come out looking a little funny, just give the corner of the ATV window another little nudge to resize it just a bit, and that usually sets things straight.

Disclaimer.

This software doesn't come with any warranty.  It may contain bugs.   Please bear in mind that this program is a work in progress, and it is gradually being updated and improved, but I don't have a whole lot of time to work on this.

The photometry and spectral extraction routines in ATV are intended primarily for quick-look analysis and not for publishable results.  They work very well in many circumstances but users should be aware that they are not as sophisticated, or as rigorously tested, as some other available tools for photometry and spectroscopy.

If you've tried atv and have any complaints, comments, bug reports, or suggestions for further improvements, write to me at barth [at] uci [dot] edu.    I don't promise to add every feature that people request, but I do keep a list to keep track of suggestions and I try to handle bug fixes relatively quickly.

Last updated August 5 2020
Back to the main atv page.