additional features

[mileslucas]

The DS9 class that is bundled with VIP https://github.com/vortex-exoplanet/VIP/blob/master/vip_hci/vip_ds9.py has some features that I use frequently and would like to see here. Perhaps they already do and I just don't realize how to use them.

Start
First, the PyDS9 package includes a method that will start the DS9 process looking in the PATH or for some pre-configured names https://github.com/ericmandel/pyds9/blob/678ebf359ccd550150eadbe2f5c59d58b8145274/pyds9/pyds9.py#L70-L91

I actually have a version of this specifically for Mac that works fine-

const APP_NAMES = ("SAOImageDS9.app", "SAOImage DS9.app")

function start(target="ds9")
    user_dir = homedir()
    local ds9_cmd
    for p in ("/Applications", user_dir, joinpath(user_dir, "Applications    "), joinpath(user_dir, "Desktop")), app in APP_NAMES
        ds9_app_dir = joinpath(p, app)
        if ispath(ds9_app_dir)
            ds9_cmd = `open -a $ds9_app_dir --args -title $target`
        end
    end
    run(ds9_cmd)
end

so all that needs to be added is a version that works for other platforms

display
In general, the VIP DS9 class has a lot of nice helpers. Things like clear_frames cmap, etc. which call simple commands internally but give a very nice functional interface. I don't think all of these are necessary, but I think it would be nice to get a list of functions we want to provide convenience methods for.

In particular, the display method of the VIP DS9 class is really nice. It automatically tiles out vararg frames for display. I'd really like to see something like this!

[emmt]

I have deliberately limited myself to providing such improvements in order to avoid them being too much biased towards my only personal taste. But I think this would be nice if we can elaborate on this subject. Perhaps we should start with a list of common and useful recipes using the basic syntax (that of DS9 set/get commands) and see wheteher something coherent emerges (this is also related to your idea of having a dedicated REPL mode in #3). There is a short list of examples in the doc. of SAOImageDS9.jl and also the VIP Python package you mentioned can be a source of inspiration.

My understanding of your start is that it launches SAOImage/DS9. It would be nice that it can (i) avoid launching a new instance if one is already running, (ii) connect to the running DS9 instance. The latter is (partialy) done in current SAOImageDS9.jl which should automatically connect to a running DS9, if any, when the module is loaded (with using or import). Automatically launching DS9 application can be added to the existing connect method since the caller is likely to connect to it right after launching.

The mechanism should also work on other platforms than MacOSX.

BTW There are at least 2 other things that are missing from the current SAOImageDS9.jl interface:

• mouse interaction;
• overplotting of symbols, lines, text, etc. in DS9 frame.

I have some premiminary code for that which I can put in a development branch to share it.

[emmt]

I had a look at the VIP Python package, some features should be straightforward to implement although we should improve the API in some places.

I had forgotten that plotting of some symbols (circles and rectangles) was already implemented in SAOImageDS9.jl as of version 0.2.0. But I added two simple methods, message and select, to display a simple message dialog and to interactively select a position in current DS9 frame.

[mileslucas]

okay, I've been digging into this a little more, here's what I've got

I propose to restructure the package like this-

src/
	SAOImageDS9.jl # configuration, includes __init__() function
    core.jl # get, set, connect, XPA interface
    utils.jl # display, draw, select, message
    repl.jl # repl-mode parser (WIP)

first off to just organize the code

Core functionality

get and set are mostly unchanged, and we can add a start method which starts the process in a platform-independent way. The start method will have keywords for attaching to existing processes if available (true by default) and to automatically call connect. Or, we can add an option to connect to automatically call start, in either case, the use-case is that users only have to issue a single start() or connect() call to having a working connection.

Utility functions

I propose we remove the array interface of draw and add a new method called display. This can take 2D or 3D arrays and if multiple are provided will automatically tile them. This is designed in the nature of the VIP ds9.display function. I think display is a more appropriate verb for images and helps organize the image-based options from the shape based options in draw. We can incorporate the config ideas from #2 into display, as well. For draw, I would also add a high-level function like draw(:ellipse; x=12, y=35, a=5, b=7) which uses if-elses to dispatch alongside the kwargs.

For additional functionality, I think instead of providing an API equivalent to DS9, we should only provide functions that are an actual convenience. For example, the VIP DS9 has a zoom method, which always ends up calling ds9.set("zoom $value"), so I don't see the utility when you could've just called the above directly (in other words, the API should just need documentation, not new functions). So, the only functions that I propose adding are match and lock, with keyword args for scale, colorbar, slice, and crosshair, such that it will call match or lock appropriately for each of the keyword arguments that is true.