### Cloud Computing with SAOImageDS9: $geturl()

> for full documentation on Analysis Files, please see Analysis

> Table of Contents

> Introduction
> Analysis menu digest
> Information about examples used in this doc
> Detailed Examples
> Summary

> Introduction

> SAOImageDS9 (DS9) can be used as an interface to cloud computing resources. Another way of saying this is that DS9 can run analysis programs remotely and receive results in many different formats: text, images, plots, and regions.

> This is made possible by using the `$geturl()` Analysis Command macro. This macro will “call” the specified URL with whatever parameters have been supplied and will display the results.

> The key is that DS9 recognizes some application specific data types that allows it to process specialized results.

> In this document we assume the reader has some cursory understanding of developing web services. Users should have some understanding of Content-Type’s (used interchangeably with MIME types), HTTP GET versus POST requests, and URL syntax. An even more cursory knowledge of Tcl/Tk and XPA is helpful.

> Analysis menu digest

> The DS9 Analysis command syntax is specified in the Reference Manual. The basics are as follows:

> The Analysis commands are written in an text file. The unofficial standard is to name the file with the `.ans` suffix, though any legal filename/suffix can be used.

> Each command uses 4 lines. For example

>     My Analysis Task
>     *
>     menu
>     my_awesome_command $parameters | $text

> Breakdown:

> 1. The name of the analysis task. For example My Analysis Task

> 2. The types of files the analysis task can be used with. This is based on the file name, not the content of the file. * is a wildcard meaning all file names. If multiple file names are expected they are separated with spaces. For example *evt* *EVT* would work with file names that contain the string evt or EVT. File names are case sensitive.

> 3. Whether this analysis task should be added to the Analysis menu or whether it should be bound (ie bind) to a Tk event. For example bind m would run the analysis task when the m button is pressed.

> 4. The actual analysis command. This can include parameters such as Analysis macros: `$filename` or `$regions`. It may also include user parameters (more on this below). The output from the command is then sent to a particular output based on where it is piped, `|. $text` will send the output from the command to a text box. `$image` will send the results to the imager.

> User settable parameters can be specific using the param section:

>     param my_pars
>       par1 entry {Hello World} {} {Enter your message in this box}
>       par2 menu {Favorite Color} {red|green|blue|green|black} {Select your fav. color}
>     endparam

> and then used in the analysis task like this:

>     My Parameters
>     *
>     menu
>     $param(my_pars); my_command $par1 $par2 | $text

> This is just a quick introduction. There are many more details and options described in the documentation.

> Information about examples used in this doc

> The details about setting up a production ready web server and writing robust web services is beyond the scope of this document.

> The basic requirement is that whatever web service is being used it has to accept an HTTP/S GET request where the URL contains both the location of the web resource as well as any processing parameters. For example

> `http://my_awesome.service.com/my_tool?par1=foo&par2=bar`

> `GET` differs from `POST` in that with `GET` the parameters are included in the URL whereas `POST` parameters are not. `POST` services allows for things like file upload which DS9 does not support.

> In this document we will be using the Flask Python based web service framework to run a local web server. By default it runs on the local machine on port 5000, ie IP address `127.0.0.1:5000`.

> The nature of the web server setup is up to the user. It could be a CGI script written in any language (C/C++, Python, Shell, Perl, etc) or a RESTful service like the examples below. The only requirement is that the service has to accept/process GET requests.

> Detailed Examples

> This section demonstrates several different remote analysis tasks. It includes a simple example of how to setup the flask web service and the DS9 Analysis Command file for various types of analysis tasks which return different types of outputs.

> Getting Started: Hello World

> Let’s create a simple file called `hello_world.py`

>     from flask import Flask, make_response

>     app = Flask(__name__)

>     @app.route("/")
>     def hello_world():
>         retval = "Hello, World!"
>         response = make_response(retval)
>         response.mimetype = "text/plain"
>         return response

> The first two lines are common to all the examples below.

> We can then start a local web server running on `http://127.0.0.1:5000`

>     flask --app hello_world run

> Next we crate the DS9 analysis command file `hello_world.ans`

>     Hello World
>     *
>     menu
>     $geturl(http://127.0.0.1:5000/) | $text

> and then run ds9

>     ds9 -analysis hello_world.ans

> (Or go to `Analysis -> Load Analysis Commands` and select the file `hello_world.ans.)`

> Then go to `Analysis -> Hello World` which will open a text box displaying the message: `Hello World.`

> The remainder of the examples in this document will follow a similar pattern where we have to write some code to be run on the web server, and add an option to the DS9 analysis file to execute that code.

> Passing parameters

> Users should be familiar with URL’s that look like

> `https://linux.is.awesome.edu/some_command?this=1&that=the_other`

> Where some_command is the web access point which is taking some parameters: this and that. These are identified in the URL as they follow the question mark (“?”) and are separated by ampersands (“&”). They take the form

> `parameter name = value`

> This is how HTTP/S “GET” requests are encoded. HTTP/S “PUT” requests are processed differently; however, ds9 only supports “GET” requests.

> It will often be the case that these parameters will be set via the DS9 Analysis menu syntax using in the `param` section.

> Below is a simple example that will just print back to the user the text they supply when prompted for the parameter:

> Simple, Single Parameter

>     from flask import request
>     @app.route("/simple_parameter/")
>     def simple_parameter():
>         user_text = request.args.get("text")
>         retval = f"The user wrote '{user_text}'"
>         response = make_response(retval)
>         response.mimetype = "text/plain"
>         return response

> the `request.args.get` method is used to retrieve specific parameters by name. Here the web service end-point simple_parameter is expecting to find a parameter named `text`.

> The DS9 Analysis File for this example looks like:

>     param simpletxt
>       usr_txt entry {Enter some text} {} {This text will be echoed back}
>     endparam

>     Simple Text
>     *
>     menu
>     $param(simpletxt); $geturl(http://127.0.0.1:5000/simple_parameter/?text=$usr_txt) | $text

> The the `param` section identifies a new parameter section: `simpletxt`. It has a single parameter named `usr_txt`, which is a text `entry` box. In the `$geturl` macro we see that we have used the “?” to identify that there are parameters and added a single parameter `text=$usr_txt`. When this analysis task is invoked from the menu, it will open a window asking the use the Enter some text. Upon submission, a text box will open with the message The user wrote ‘blah’ where blah is whatever the user wrote.

> Multiple parameters

> Multiple parameters are handled in the same way. They are simply separated by ampersands.

> It is beyond the scope of this document, but users should be aware that certain characters have special encoding when present in a GET URL. This includes question marks, ampersands, and spaces.

> Below is the python bit that can read multiple parameter values

>     @app.route("/multi_parameter/")
>     def multi_parameter():

>         retval = "Found the following parameters\n"
>         for key in request.args:
>             retval += f"{key} = {request.args[key]}\n"

>         response = make_response(retval)
>         response.mimetype = "text/plain"
>         return response

> This bit of code just loops over whatever parameters are present in the URL. It will print the key = value pairs in a text window.

> The DS9 Analysis bit looks like:

>     param multiparam
>       usr_txt2 entry {Enter some text} {} {This text will be echoed back}
>       func menu {Function} min|max|median {An example of a select box}
>       check checkbox {Yes/No} 1 {Checked is 1, Unchecked is 0}
>     endparam

>     Multi Params
>     *
>     menu
>     $param(multiparam); $geturl(http://127.0.0.1:5000/multi_parameter/?text=$usr_txt2&func=$func&par3=$check) | $text

> Where here again we have defined a new set of parameters in the param section.

> You cannot use the same parameter name in different parameter sections. It can result in unpredictable results. Use unique parameter names in each param section.

> The `$geturl` macro then has the parameters encoded using ampersand seperated `key=value` pairs.

> X-XPA/XPASET mime-type

> HTTP/S allows content creators to use custom Content-Type’s for specialized “media” types. The convention is to preface the custom type with an `x-`. DS9 recognizes the `x-xpa/xpaset` content type. With this Content-Type services can send xpaset commands to DS9.

> The `X-XPA/XPASET` requires two parameters:

> 1. `target` : this is the XPA access point to send the commands to. Note that setting this to simply “ds9” will send the same XPA command to all instances of DS9 that are running. To specify a specific instance of DS9, ie the one that actually sent the $geturl request, you need to use the $xpa_method macro.

> 2. `paramlist` : this is the actual XPA command to run.

> Additional data needed by the `xpaset` command should then be included in the body of the response.

> This example shows how to create a region and return it back to DS9

>     @app.route("/region/")
>     def send_region():
>         target = request.args.get("target")
>         retval = "physical; circle(4096.4,4096.5,100)"
>         response = make_response(retval)
>         response.headers['Content-Type'] = f'x-xpa/xpaset; target="{target}"; paramlist="regions -format ds9"'
>         return response

> would be the equivalent of running

> `

> echo "physical; circle(4096.4,4096.5,100)" | xpaset $target regions -format ds9

> `

> from the command line. That is the data that on the command line would be input via stdin, is included in the body of the response.

> The DS9 analysis command looks like:

>     Simple Region
>     *
>     menu
>     $geturl(http://127.0.0.1:5000/region/?target=$xpa_method) | $text

> DS9 cannot accept xpaget requests. get requests requires two way communication with the application. The `$geturl` requires that all data and parameters that the service requires be supplied in the `$geturl` request itself.

> Multi-part mime-type

> Some services may need to send back information in more than one `xpaset` request. To accommodate this, DS9 recognizes the `multipart/mixed` Content-Type. While this is common when dealing with email messages, it is not common for HTTP/S. However it is perfectly legal/valid.

> The syntax for a `multipart/mixed` message includes that as the Content-Type, and includes a boundary string that is used to separate the content of each embedded message. The boundary should be a unique character string that is guaranteed not to be part of the body of any of the embedded messages.

> Below is a simple example that runs 3 xpaset commands

> 1. `xpaset -p $target cmap bb` to set the color map to “bb”
> 2. `xpaset -p $target scale log` to change to log scaling
> 3. `xpaset -p $target scale limits 0 10` to change the scale limits to go from 0 to 10.

>     BOUNDARY = "xpamime:142857:285714:428571:571428:714285:857142"

>     @app.route("/cmap/")
>     def multi_cmds():

>         def wrap_cmd(cmd):
>             retval = f'--{BOUNDARY}\n'
>             retval += f'Content-Type: x-xpa/xpaset; target="{target}"; paramlist="{cmd}"\n\n'
>             return retval

>         target = request.args.get("target")
>         cmd1 = "cmap bb"
>         cmd2 = "scale log"
>         cmd3 = "scale limits 0 10"

>         retval = wrap_cmd(cmd1)
>         retval += wrap_cmd(cmd2)
>         retval += wrap_cmd(cmd3)
>         retval += f'--{BOUNDARY}'

>         response = make_response(retval)
>         response.mimetype = f'multipart/mixed; boundary="{BOUNDARY}"'
>         return response

> When the boundary is used it is prefixed with two dashes, `--`

> The last command must be followed by a trailing boundary line.

> The DS9 analysis command menu syntax looks like:

>     Multi Commands
>     *
>     menu
>     $geturl(http://127.0.0.1:5000/cmap/?target=$xpa_method) | $text

> Note that these commands are completely independent. Setting the color map, changing the scaling, and changing the scale limits are independent actions. Each command in a multipart/mixed message is independent. They are processed in order but do not have to be related. Also note that none of these commands require any additional data; that is the body of each part if blank. (This is the two new-line characters, \n, after the `paramlist`.)

> Returning a plot

> Plots can be created using the XPA `plot` command.

> However plot commands must be wrapped inside a `multipart/mixed` content.

> In this example we plot X vs X^2 for x in the range from 0 to 9 and then modify the plots appearance with additional xpa commands:

>     @app.route("/plot/")
>     def send_plot():

>         def make_plot(xx,yy):
>             vals = [f"{x} {y}" for x, y in zip(xx, yy)]

>             plot_cmd = 'plot line {My Title } {X Label} {Y Label } xy'
>             retval = f'--{BOUNDARY}\n'
>             retval += f'Content-Type: x-xpa/xpaset; target="{target}"; paramlist="{plot_cmd}"\n\n'
>             retval += "\n".join(vals)+"\n"

>             plot_cmd = 'plot line smooth step'
>             retval += f'--{BOUNDARY}\n'
>             retval += f'Content-Type: x-xpa/xpaset; target="{target}"; paramlist="{plot_cmd}"\n\n'

>             plot_cmd = 'plot background lightblue'
>             retval += f'--{BOUNDARY}\n'
>             retval += f'Content-Type: x-xpa/xpaset; target="{target}"; paramlist="{plot_cmd}"\n\n'

>             retval += f'--{BOUNDARY}\n'
>             return retval

>         target = request.args.get("target")
>         xx = list(range(10))
>         yy = [x*x for x in xx]

>         retval = make_plot(xx, yy)
>         response = make_response(retval)
>         response.mimetype = f'multipart/mixed; boundary="{BOUNDARY}"'
>         return response

> Note that Python (sometimes) will treat curly brackets special and so does Tcl. In Python you may sometimes need to used double curly brackets when you want to pass a single curly bracket to Tcl. In this example since the `plot_cmd` variable does not do any formatting so we need to used single curly brackets. In Tcl, strings that contain spaces need to be wrapped in curly brackets.

> The DS9 analysis command for this is:

>     Simple Plot
>     *
>     menu
>     $geturl(http://127.0.0.1:5000/plot/?target=$xpa_method) | $text

> Note: It is possible to send bare plots (just values, no title, no labels, all default plot options) using the $plot macro (without any options). In this case the values can be returned as just a simple text/plain Content-Type.

> Returning images

> Returning an image can be a bit more complicated.

> Simple case: Single images with properly configured web server

> In the most simple case, if the web service is only going to return a single image then rather than using `$geturl()` you should just use `$url()` which is piped into the `$image` macro.

> In this example we have a local file: `/export/img.fits` that we want to return via the `/get_img` end point. We can do something like this:

>     @app.route("/get_img")
>     def get_img():

>         retval = open("/export/img.fits", "rb").read()
>         response = make_response(retval)
>         response.headers['Content-Type'] = "image/fits"
>         return response

> It is important that the FITS image is read in as a pure binary/byte array (the b in the rb mode). Equally important is that the Content-Type has been set to the standard `image/fits` mime-type used for FITS images. If the Content-Type is not properly set to image/fits then the results are unpredictable.

> Then in the DS9 analysis file the command looks like:

>     Basic Image
>     *
>     menu
>     $url(http://127.0.0.1:5000/get_img) | $image(new)

> `$url` is used instead of `$geturl`. The output is piped to the `$image(new)` macro which will create a new frame to load the image.

> The URL passed to $url can contain the same GET encoded syntax as shown before, eg

>     $param(something); $url(https://awesome.edu/endpoint?par1=$par1&par2=$par2) | $image

> Using `fits` XPA access point.

> The second technique to load an image is to use the `fits` XPA access point. This is necessary if there are multiple images to be returned (eg if doing a 2D fit which requires sending back separate images for the model and residual). It can also be useful if the output from the service contains multiple different outputs such as an Image and a Region to draw on that image.

> The trick is that the raw, binary FITS image cannot be used directly. The image must be gzip’ed and it must be encoded into ASCII using base64 encoding.

> This is an example of how to convert the binary FITS file to ASCII:

>     def _convert_image(infile):
>         'Load image, gzip, and base64 encode it'

>         import gzip
>         import io
>         import base64
>         import textwrap

>         # Load the image as raw bytes
>         with open(infile, 'rb') as fp:
>             img_data = fp.read()

>         # Compress the image in memory
>         compressed_buffer = io.BytesIO()
>         with gzip.GzipFile(fileobj=compressed_buffer, mode="wb") as fp:
>             fp.write(img_data)

>         # Encode compressed image w/ base64
>         compressed_buffer.seek(0)   # rewind
>         img_base64 = base64.b64encode(compressed_buffer.getvalue())

>         # Format into 80 chars wide
>         retval = textwrap.fill(img_base64.decode('ascii'), width=80)
>         return retval

> The data are read-in as binary data. The data are then compressed, in memory, using gzip. The compressed data are then base64 encoded to ASCII. Then finally the ASCII is formatted to be 80 characters wide, which is generally standard for base64 messages.

> We can use this conversion routine to setup our image server end point. Just as with the Plot example, the fits commands have to be wrapped inside a `multipart/mixed` container. This technique requires setting `Content-Transfer-Encoding: base64` in the header.

>     @app.route("/image/")
>     def send_image():

>         def multipart_wrap(image):
>             retval = f'--{BOUNDARY}\n'
>             retval += f'Content-Type: x-xpa/xpaset; target="{target}"; paramlist="fits new sample_img.fits.gz"\n'
>             retval += 'Content-Transfer-Encoding: base64\n\n'
>             retval += image
>             retval += f'\n--{BOUNDARY}\n'
>             return retval

>         target = request.args.get("target")
>         image = _convert_image("/export/img.fits")
>         retval = multipart_wrap(image)
>         response = make_response(retval)
>         response.mimetype = f'multipart/mixed; boundary="{BOUNDARY}"'

>         return response

> In this example we used the fits new command so that the image will be loaded into a new frame.

> The DS9 analysis command looks like:

>     Complex Image
>     *
>     menu
>     $geturl(http://127.0.0.1:5000/image/?target=$xpa_method) | $text

> Using this technique users can return multiple images (eg if needed for RGB, HSV or HLS frames) or images and associated regions, etc.

> Download an arbitrary file

> This technique uses XPA to control the built in web browser to download an arbitrary file. The browser window will open and then close when the download is complete. This requires two different end-points to our service

> 1. The end point URL that is called from DS9 to initiate the download, similar to our other examples. This first URL will have the DS9 browser open the 2nd URL.
> 2. The end point that serves the file.

>     @app.route("/web/")
>     def send_web():
>         target = request.args.get("target")
>         retval = f'--{BOUNDARY}\n'
>         retval += f'Content-Type: x-xpa/xpaset; target="{target}"; paramlist="web http://127.0.0.1:5000/get_file"\n\n'
>         retval += f'--{BOUNDARY}\n'
>         retval += f'Content-Type: x-xpa/xpaset; target="{target}"; paramlist="web close"\n\n'
>         retval += f'--{BOUNDARY}\n'
>         response = make_response(retval)
>         response.mimetype = f'multipart/mixed; boundary="{BOUNDARY}"'
>         return response

>     @app.route("/get_file")
>     def get_file():
>         import os
>         infile = "/export/img.fits"
>         fname = os.path.basename(infile)
>         retval = open(infile, "rb").read()
>         response = make_response(retval)
>         response.headers['Content-Type'] = f"Content-Type: application/octet-stream;name={fname}"
>         return response

> This first URL end point, `/web` is what DS9 will be use in the analysis menu, ie

>     Download File
>     *
>     menu
>     $geturl(http://127.0.0.1:5000/web/?target=$xpa_method) | $text

> The `/web` endpoint then makes two XPA calls. The first call is to open the web browser and load the second URL endpoint, `/get_file`. The `/get_file` end point then open a file and reads it into memory as raw bytes (the b in rb). It then serves the file with Content-Type as `application/octet-stream.` This MIME type is used to convey an arbitrary data file which will cause the DS9 browser to prompt the user to save the file. The file name `name={fname}` will be the default name. After the file is saved then the /web endpoint closes the web browser window. For small files, served locally the browser window may just “flash” on the screen for an instance.

> This technique could be used to return any arbitrary results including thing such as PDF files, non-image FITS files (ie FITS tables), or any random file that is not intended to be “consumed” by DS9 directly.

> Summary

> This document describes how to use DS9 as an interface to cloud computing resources. It demonstrates how to handle various types of returned information including text, regions, plots, images, and arbitrary data files. It provides some guidance with respect to best practices when writing the cloud based applications.