CASA Viewer DS9 Region Support
Links
Download latest DS9: http://hea-www.harvard.edu/RD/ds9/
DS9 Region File Specification: http://hea-www.harvard.edu/RD/ds9/ref/region.html
Notes on DS9 File Specification
- Different versions of DS9 may produce different file formats. The viewer's DS9 file loader should work with the newest specification (version 4.1) and some/most of the previous version (3.0). The newest version of DS9 (5.3) produces files in the 4.1 specification.
- On colors: DS9 allows for 8 standard color names or custom colors in the newest version. Custom colors in DS9 are not given guidelines for their format, so the viewer accept them in hexadecimal form (i.e. 000000 or #000000).
- In the DS9 file specification, the annulus shapes seem to have an alternate form using an "n=#" parameter. This is not supported (and doesn't seem to work in DS9, either).
- Although the file specification says that sexagesimal coordinates should be in pairs (the first H:M:S and the second D:M:S), in the case of Galactic DS9 saves in D:M:S D:M:S format.
- Although this is not documented, sometimes DS9 puts the comment in front of the region instead of between the coordinates and the properties.
Terminology
What DS9 calls "regions" are not analogous to CASA's "regions". DS9 regions are closer to what CASA calls "display shapes" or "annotations". In this document and the viewer, the terms "region shapes" or "shapes" are used for these changes.
Coordinate Systems
- Unsupported DS9 coordinate systems: Linear, Amplifier, Detector, multiple WCS.
- "Image" and "Physical" DS9 systems both map to CASA "Pixel" system.
- DS9's ecliptic seems to be different from CASA's ecliptic. [1]
- Converting between different coordinate systems in CASA may cause some weirdness with negative/positive values. For example, although -70 and +290 degrees are the same value, CASA coordinate systems may not do the correct thing if they are expecting one sign and get another. There are checks in the region shapes to try to catch this, but it could still pop up unexpectedly.
- The way rotation angles are calculated in DS9 are a bit strange, so don't expect the values to match the values you see on the viewer's region shape editor.
Other/Miscellaneous
- Unsupported DS9 regions: ruler, compass, projection, panda, elliptical panda, box banda. [3]
- Arrow point is converted to an X point.
- Template regions not supported.
- DS9 properties not used/supported: select, highlite, edit, move, delete, fixed, tag (group), dashlist, composite angles.
- Bold/italic fonts and dashed/dotted lines will only work with QtPixelCanvas and not other subclasses of PixelCanvas (this shouldn't be a problem unless CASA moves away from Qt and makes a new viewer).
- Text location may be slightly off due to Qt text-drawing weirdness.
- DS9 bug (as of 5.3): text angle is not saved to the file when it's 0 in pixel (even if file coordinates aren't pixel). This means that if there is unrotated text that is saved in a world system, it will be 0 degrees in that system rather than 0 degrees on the screen.
- In the viewer, loading region shapes in world coordinates when the image has more than two world axes doesn't work due to how the different coordinate systems interact.
- Nested composite shapes are not allowed.
Saving to DS9 Format
- All font families are saved as "helvetica".
- If the shape has a linethrough, the DS9 region has the exclude property. All linethrough properties are discarded.
To-Do List
- Changing polygon coordinates and composite children after creation.
- Supporting additional shapes. (See [3].)
- Edit/move/create region shapes using the mouse.
- Look into / fix / implement [1] and [2].