CARTA wrapper script

[Jordatious]

Hey @confluence and @ajm-asiaa, let me know if there's a better place to discuss this. I've been playing with the CARTA python scripting, and have written a wrapper script for connecting to a server/controller instance or desktop application (only tested on Mac OSX for now). It's working quite nicely! I'm still developing it for my own purposes, but I thought it would be useful to share, as well as ask some questions / make some suggestions while I continue to develop it.

The server/controller instance works in the normal way, from any location where an authorised token exists. I do find the authentication step takes quite a while, which is an overhead that doesn't exist when scripting within a python session rather than making separate calls of such a wrapper script. But perhaps there's a way to make this more efficient?

The desktop application works in a slightly clunky way, as it calls an executable @confluence had me create, located in /Applications/CARTA.app/Contents/Resources/app/carta-backend/bin/carta.sh, with the following contents:

#!/bin/bash

dirname=`dirname $0`

DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )/../etc"

export CASAPATH="../../../../$DIR linux"

$dirname/casa_data_autoupdate

$dirname/carta_backend $@ --frontend_folder=$dirname/../../

I can launch this with an alias carta, ensuring I pass in --enable_scripting. This then launches a Chrome window without my preferences retained, outputting the session ID and token, which I can pass into my script to interact with this session. Alternatively, I can start a new session, which launches in a profile-less Chrome window, which also doesn't retain my preferences.

Here are some issues that would be great to address:

1. It would be good to have Mac OSX desktop application launch within the electron app.
2. As I mentioned, when connecting to an existing instance or a new instance of the desktop application, my preferences are not retained
3. It would be good to have an existing executable from the CARTA package (or even the carta alias) support CARTA scripting, without having the create a new executable
4. In general, I'm finding there are very few accessors / getters for extracting information from the existing session / images. For instance, when I set the bias/contrast, I don't seem to be able to pass None in as the colormap, but have to specify something. I'm using the default of inferno / carta.constants.Colormap.INFERNO, but if the user has selected something else via the GUI, it will change their colormap. Are there additional accessors I'm not seeing documented?
5. There are occasional issues with connecting to an existing server/controller session, even though I can interact with it via the GUI; often the backend will disconnect as I try to interact with it via the scripting interface
6. Similarly, there are frequent issues saving a figure from a server/controller instance; initially I thought this was because of my security preferences when saving to a directory other than ~/Downloads via a profile-less Chrome window, but I did eventually get it working after several attempts

[Jordatious]

I can't seem to upload a Python file, so here's the contents of run-carta.py:

#!/usr/bin/env python3

import argparse,webbrowser,os

from carta.session import Session
from carta.protocol import Protocol
from carta.token import ControllerToken,BackendToken
from carta.util import CartaRequestFailed,CartaBadToken,CartaActionFailed
from carta.browser import Chrome

chromeOptions = ['--force-device-scale-factor=4', '--window-size=1200,800']

def parse_args():

    """Parse arguments into this script.

    Returns:
    --------
    args : class ``argparse.ArgumentParser``
        Known and validated arguments."""

    parser = argparse.ArgumentParser(description='Run CARTA via a desktop application or server/controller instance.')

    instance_args = parser.add_mutually_exclusive_group(required=True)
    instance_args.add_argument("-S","--server", action='store_true', required=False, default=False, help="Use CARTA server/controller given by [-U --URL]")
    instance_args.add_argument("-D","--desktop", action='store_true', required=False, default=False, help="Use CARTA Desktop Application given by [-e --executable]")

    sesh = parser.add_argument_group('Session Arguments')
    sesh.add_argument("-s","--sessionID", metavar="ID", required=True, type=int, help="Session ID (use 0 to launch new instance)")
    sesh.add_argument("-U","--URL", metavar="URL", default="https://carta.idia.ac.za", required=False, type=str, help="URL of server version to interact with")
    sesh.add_argument("-T","--token", metavar="path", required=False, default='~/carta-token', type=str, help="Path to token (existing, or to be created)")
    sesh.add_argument("-N","--username", metavar="username", required=False, type=str, default='jcollier', help="Username for CARTA server/controller hosted at [-U --URL]")
    sesh.add_argument("-E","--executable", metavar="Local path", required=False, type=str, default='/Applications/CARTA.app/Contents/Resources/app/carta-backend/bin/carta.sh', help='Path to local CARTA executable (desktop)')

    sesh.add_argument("-H","--headless", action='store_true', required=False, default=False, help="Run headless browser")
    sesh.add_argument("-C","--close", action='store_true', required=False, default=False, help="Close new session (i.e. [-s --sessionID] 0) automatically (without pressing return)")

    img = parser.add_argument_group('Image Operations')
    img.add_argument("-I","--images", metavar="paths", action='append', required=False, type=str, help="Paths of images to open (append further images with additional call of [-I --images])")
    img.add_argument("-i","--index", metavar="image", required=False, type=int, help="Image index to apply an image operation toward, with 1 as the first index (use 0 for all images). Default is active frame.")
    img.add_argument("-P","--percentile", metavar="rank", required=False, type=float, help="Percentile rank") # default=99.9,
    img.add_argument("-z","--zoom", metavar="Zoom level", required=False, type=float, help='Set Zoom level')
    img.add_argument("-c","--contrast", metavar="Bias and contrast level", nargs=2, required=False, type=float, help='Set bias and contrast')
    img.add_argument("-e","--exportPath", metavar="Local path", required=False, type=str, help="Save current/final view to this local path")

    img.add_argument("-R","--lockRaster", action='store_true', required=False, default=False, help="Lock raster scaling")
    img.add_argument("-W","--lockWCS", action='store_true', required=False, default=False, help="Lock WCS")
    img.add_argument("-F","--lockFreq", action='store_true', required=False, default=False, help="Lock frequency")

    args, unknown = parser.parse_known_args()

    if len(unknown) > 0:
        parser.error('Unknown input argument(s) present - {0}'.format(unknown))

    return args


def server_session(URL, username, token, sessionID, headless):

    try:
        if sessionID == 0:
            session = Session.create(Chrome(headless=headless,options=chromeOptions), URL, ControllerToken.from_file(token))
        else:
            session = Session.interact(URL, sessionID, ControllerToken.from_file(token))
    except (CartaBadToken,CartaRequestFailed):
        Protocol.request_refresh_token(URL, username, token)
        session = server_session(URL, username, token, sessionID, headless)

    return session

def desktop_session(URL, executable, token, sessionID, headless):

    if sessionID == 0:
        session = Session.start_and_create(Chrome(headless=headless,options=chromeOptions), executable)
    else:
        if '?token=' in URL:
            session = Session.interact(URL, sessionID)
        else:
            session = Session.interact(URL, sessionID, BackendToken(token))

    return session

def run_carta(server, desktop, headless, executable, URL, username, token, sessionID, images, lockRaster, lockWCS, lockFreq, percentile, zoom, contrast, exportPath, close, index):

    if 'https://' not in URL and 'http://' not in URL:
        URL = 'https://' + URL

    if '~' in token:
        token = os.path.expanduser(token)

    if server:
        session = server_session(URL, username, token, sessionID, headless)
    elif desktop:
        session = desktop_session(URL, executable, token, sessionID, headless)

    if sessionID == 0:
        print('Started session with ID: {0}'.format(session.session_id))

    if images:
        for i,image in enumerate(images):
            try:
                session.append_image(image)
            except CartaRequestFailed as err:
                if str(sessionID) in str(err):
                    print(err)
                    webbrowser.get('chrome').open(URL)
                    session.close()
                    sessionID = int(input('Enter session ID (right-click --> Inspect --> Console): '))
                    run_carta(server, desktop, headless, executable, URL, username, token, sessionID, images, lockRaster, lockWCS, lockFreq, percentile, zoom, contrast, exportPath, close, index)
                    return
                else:
                    raise CartaRequestFailed(err)

    imgs = session.image_list()

    if index is None:
        img = session.active_frame()
        image_operations(img,percentile,zoom,lockRaster,lockWCS,lockFreq,contrast)
    elif index > 0:
        if index > len(imgs) + 1:
            print("Index {0} out of bounds. Only {1} frames present.".format(index,len(imgs)))
        else:
            img = imgs[index-1]
            image_operations(img,percentile,zoom,lockRaster,lockWCS,lockFreq,contrast)
    elif index == 0:
        for img in imgs:
            image_operations(img,percentile,zoom,lockRaster,lockWCS,lockFreq,contrast)

    if exportPath:
        session.save_rendered_view(exportPath)

    if not close and not headless:
        input('Press return to close session: ')

    if sessionID != 0:
        session.close()

def image_operations(img,percentile,zoom,lockRaster,lockWCS,lockFreq,contrast):

    if percentile:
        img.set_percentile_rank(percentile)
    if zoom:
        img.set_zoom(zoom)
    if lockRaster:
        img.set_raster_scaling_matching(True)
    if lockWCS:
        img.set_spatial_matching(True)
    if lockFreq:
        img.set_spectral_matching(True)
    if contrast:
        bias,contrast = contrast
        img.set_colormap('inferno',bias=bias,contrast=contrast) #TODO: get actual colormap

def main():

    args=parse_args()
    kwargs=vars(args)
    run_carta(**kwargs)

if __name__ == "__main__":

    main()

[confluence]

Thanks for this feedback, @Jordatious . I will respond in more detail later, but very briefly:

1 and 3 are Electron packaging issues -- I'll let @ajm-asiaa comment. I agree that the normal Electron app executable should support scripting out of the box -- this would require a) a way to pass in --enable_scripting (this might work already) and b) a way to extract the URL with the correct token from the running Electron app.

2: Did we not confirm that this was a carta / carta-beta preferences issue? We have separate user directories for release and beta packages. The same electron app should access the same directory regardless of how you launch it; changing between beta and release packages will always access different directories regardless of the package or invocation method.

4: This is a known issue; @kswang1029 is currently making a lot of suggestions for extending and fixing the high-level API (there are multiple issues open for this; you are welcome to file additional issues for specific problems with these functions as you find them). You can always access the low-level actions, but this isn't very user-friendly. The low-level actions will be easier to discover once there are generated frontend docs (coming soon).

5: I think this is an idle timeout issue; this should be filed as an issue in the controller repo -- I think we need some way of flagging that a session is being used for scripting and should be kept alive.

6: If this is intermittent, it could be another side-effect of 5. It would be helpful to have more step-by-step information.

[Jordatious]

Thanks for the response @confluence! I'm also keen to hear if you think this is a useful "wrapper of a wrapper", or have some suggestions for improvement, including for the large authentication overhead! Here's some further responses:

1 and 3 - yes, that sounds sensible. I can't pass --enable_scripting into one of the existing executables that comes with the CARTA app out of the box. So please let us know what's possible @ajm-asiaa!

2: Yes, my apologies, this is actually working. I certainly updated my preferences for a previous stable release, which don't seem to have been retained. Perhaps it was communicated for the v3 release that preferences were reset?

4: Alright thanks. Can I get a link to those methods?

5: Alright thanks. Shall I create this issue?

6: Basically I simply launch the IDIA CARTA controller / server, open a file and try to export the image, and sometimes it hangs for a while before timing out and not exporting the image.

[confluence]

Hi, @Jordatious. I'll have a detailed look at this when I get back from leave, but in the meantime please do file that issue, and you can look up what low-level actions and properties are available by browsing the tree of stores in the frontend source. The "app store" is at the top level; this is the default starting position of paths passed to the session's call_action method.

You can look at the implementation of the higher-level API functions in the wrapper's session and image classes to see how to use these paths with call_action. The call_action and get_value methods on the image class automatically prepend the image's own path, so you use them with paths relative to that image's "frame store".

(In future we should have generated documentation for this API, and I'm also planning to add unix-like navigation commands to the wrapper to allow script writers to explore this tree interactively.)

[ajm-ska]

@Jordatious @confluence I'm sorry about my slow response. I have looked into it. The Electron version of CARTA does not pass the --enable_scripting flag. We could modify the Electron start-up script to do so, but there would be another problem; the user would not be unable to find the URL (port number and the random token) anywhere. That is because, for the Electron version of CARTA, the Electron startup script first generates a random token, selects a free port number, and then starts up the carta_backend as a background process with those values.

However, perhaps @I-Chenn's frontend branch #2070 may be able to determine that information and show it somewhere on the frontend GUI in the Electron window.

Assuming #2070 could show the URL/SessionID in the frontend, what do you think about the Electron version having the --enable_scripting flag turned on by default?
I can't imagine any downside to it?
I am just suggesting it because I feel the Electron version of CARTA is primarily for use without the command line. I know we can make a slightly awkward alias to the app's executable in order to start it up from the terminal, but I would say most users of this version simply click the CARTA icon in the Launchpad. Although, I know if a user does want to do Python scripting, then they would be likely using a terminal anyway. But still, I feel it would be slightly easier to use - the user would just click the CARTA icon in the Launchpad, Copy & Paste their URL/SessionID from the frontend, and then they are ready to go with their python scripting.

An alternative, assuming the user really wants to use the Electron window for the frontend and not the newly bundled carta.sh script (which skips the Electron component and uses the system's default web-browser for displaying the frontend), is that we could modify the Electron start-up script and have it print out the URL/SessionID that it is using in the terminal. This would only be feasible when starting CARTA using an alias in the command line.

Here is an example,
Say the alias for "carta" runs "/Applications/CARTA.app/Contents/MacOS/CARTA".
We modify the Electron startup script (main.js) to accept --enable_scripting and to print the URL and Session ID.
The user types carta --enable_scripting.
Then the terminal would print something like:

CARTA Electron desktop version - scripting mode active
URL: http://localhost:54432
Session ID: 4240141704

But please keep in mind that Electron version of CARTA is designed to not accept all carta_backend flags because of the way it starts the carta-backend separately in the background. If you run /Applications/CARTA.app/Contents/MacOS/CARTA --help you can see it does not accept all the carta-backend flags:

CARTA Electron desktop version
Usage:
carta []             CARTA file browser will default to the current path.
      [<path>]       CARTA file browser will default to the specified    
                     path <path> e.g. carta ~/CARTA/Images               
      [<image>]      CARTA will directly open the image named <image>    
                     e.g. carta aJ.fits or carta ~/CARTA/Images/aJ.fits  
      --help         View this help output.                              
      --debug        Open the DevTools in the Electron window.    

So although we could add the ability to --enable_scripting, the user would be unable to use any other carta-backend flags such as --log_protocol_messages etc. Hopefully that would not be an issue?

[kswang1029]

For the electron app, we would need to fit the capability here https://carta-python.readthedocs.io/en/latest/carta.html#module-carta.backend where a backend executable can be specified (automatically ideally).

Can the electron app dynamically feed the enable_scripting flag to start carta_backend when we set a custom electron flag (cf —help —debug) such as —scripting?

[ajm-ska]

Can the electron app dynamically feed the enable_scripting flag to start carta_backend when we set a custom electron flag (cf —help —debug) such as —scripting?

Yes. The Electron app could be modified accept a flag of a different name (e.g. --scripting) and pass it as --enable_scripting to the carta_backend process that it starts up.

[Jordatious]

Hi all,

Sorry I completely forgot about this while travelling recently! Here are my quick responses.

Assuming #2070 could show the URL/SessionID in the frontend, what do you think about the Electron version having the --enable_scripting flag turned on by default?

Yes, I like this idea!

But still, I feel it would be slightly easier to use - the user would just click the CARTA icon in the Launchpad, Copy & Paste their URL/SessionID from the frontend, and then they are ready to go with their python scripting.

I agree this is a good use case! But I think it would be good to support both, so I also like this idea!

The user types carta --enable_scripting.
Then the terminal would print something like:

CARTA Electron desktop version - scripting mode active
URL: http://localhost:54432
Session ID: 4240141704

[ajm-ska]

@Jordatious I have created a modified CARTA macOS Electron version for testing the previously mentioned scenarios. I will upload it to Slack so you can try it.

I added --enable_scripting to /Applications/CARTA.app/Contents/Resources/app/carta-backend/bin/run.sh so that it will always be enabled for the macOS Electron version.

The carta-frontend's src/components/Menu/RootMenuComponent.tsx will need to be modified in order to work with the Electron version. At the moment, when we go to File > Server > Copy Session URL to clipboard, it copies something like this:

file:///Applications/CARTA.app/Contents/Resources/app/index.html?socketUrl=ws://localhost:55051&token=c533b90f-5bf1-4814-b81c-a889a35e79d8

I'm sure it will be easy to fix. I guess an extra loop can be added to check for the presence of "socketUrl" in the string, and if present it could take the value of socketUrl, as well as substitute "ws" with "http", and "&" with "?" (Replacing "&" with "?" is necessary as the python scripting interface does not seem to be able to parse it "&").

If the user prefers to start CARTA via an alias, I have modified the /Applications/CARTA.app/Contents/Resources/app/main.js. The only tricky part was how to get the carta-backend's Session ID because the Electron version starts the carta-backend as a background child process. I solved it by checking its stdout for the word "Session" and taking the number after it e.g.

      run.stdout.on('data', (data) => {
          const regex = /Session (\d+) \[/;
          const matches = data.toString().match(regex);
          if (matches) {
              const sessionNumber = matches[1];
          }

Now, if the flag --scripting is added, you will see something like this in the terminal (I am open to re-wording it):

acdc@almac ~ % carta --scripting
CARTA Electron desktop version - Python scripting connection information:
URL: http://localhost:55051?token=c533b90f-5bf1-4814-b81c-a889a35e79d8
Session ID: 2016073487

That URL and Session ID can be entered into the python script and it appears to work.

I thought we should use a different flag here i.e. --scripting and not --enable_scripting, as it not really enabling scripting because we are leaving it enabled by default in this version.

Comments and/or suggestions are welcome.