FireflyClient

class firefly_client.FireflyClient(host='localhost:8080', channel=None, basedir='firefly', html_file=None)

Bases: ws4py.client.threadedclient.WebSocketClient

For Firefly client to build interface to remotely communicate to the Firefly viewer.

Parameters:

host : str

Firefly host.

channel : str

WebSocket channel ID.

basedir : str

basedir for the url, e.g. ‘firefly’ in ‘http://localhost:8080/firefly‘

Attributes Summary

ACTION_DICT	Definition of Firefly action (dict).
ALL	All events are enabled for the listener (str).
EXTENSION_TYPE	Type of plot where the extension is added to (list of str).
LO_VIEW_DICT	Definition of layout viewer (dict).
STRETCH_ALGORITHM_DICT	Definition of stretch algorithm (dict).
STRETCH_TYPE_DICT	Definition of stretch type (dict).

Methods Summary

add_cell(row, col, width, height, element_type)	Add a slate viewer cell.
add_extension(ext_type[, plot_id, title, ...])	Add an extension to the plot.
add_listener(callback[, name])	Add a callback function to listen for events on the Firefly client.
add_mask(bit_number, image_number, plot_id)	Add a mask layer.
add_region_data(region_data, region_layer_id)	Add region entries to a region layer with the given ID.
create_image_url(image_source)	Create image url or data uri according to the image source.
delete_region_layer(region_layer_id[, plot_id])	Delete region layer from the loaded FITS images.
disconnect()	Disconnect the WebSocket.
dispatch_remote_action(channel, action_type, ...)	Dispatch the action to the server by using ‘GET’ request.
dispatch_remote_action_by_post(channel, ...)	Dispatch the action to the server by using ‘POST’ request.
fetch_table(file_on_server[, tbl_id, page_size])	Fetch table data without showing them
get_firefly_url([mode, channel])	Get URL to Firefly Tools viewer and the channel set.
launch_browser([url, channel, force])	Launch a browser with the Firefly Tools viewer and the channel set.
overlay_region_layer([file_on_server, ...])	Overlay a region layer on the loaded FITS images.
received_message(m)	Override the superclass’s method
reinit_viewer()	re-initialize the viewer
remove_listener(callback[, name])	Remove an event name from the callback listener.
remove_mask(plot_id, mask_id)	Remove a mask layer from the plot with the given plot ID.
remove_region_data(region_data, region_layer_id)	Remove region entries from a region layer with the give ID.
set_pan(plot_id[, x, y, coord])	Relocate the image to center on the given image coordinate or EQ_J2000 coordinate.
set_stretch(plot_id[, stype, algorithm])	Change the stretch of the image (no band case).
set_zoom(plot_id[, factor])	Zoom the image.
show_chart([group_id])	Show a plot.ly chart
show_coverage([viewer_id, table_group])	Show image coverage associated with the active table in the specified table group
show_fits([file_on_server, plot_id, viewer_id])	Show a FITS image.
show_fits_3color(three_color_params[, ...])	Show a FITS image by giving the three color requirement
show_histogram(tbl_id[, group_id])	Show a histogram
show_image_metadata([viewer_id, table_group])	Show the image associated with the active (image metadata) table in the specified table group
show_table([file_on_server, tbl_id, title, ...])	Show a table.
show_xyplot(tbl_id[, standalone, group_id])	Show a XY plot
stay_connected()	Keep WebSocket connected.
upload_data(stream, data_type)	Upload a file like object to the Firefly server.
upload_file(path[, pre_load])	Upload a file to the Firefly Server.
upload_fits_data(stream)	Upload a FITS file like object to the Firefly server.
upload_text_data(stream)	Upload a text file like object to the Firefly server.
wait_for_events()	Wait over events from the server.

Attributes Documentation

ACTION_DICT = {'ShowFits': 'ImagePlotCntlr.PlotImage', 'AddExtension': 'ExternalAccessCntlr/extensionAdd', 'FetchTblData': 'table.fetch', 'ShowTable': 'table.search', 'ShowXYPlot': 'charts.data/chartAdd', 'ShowPlot': 'charts.data/chartAdd', 'ZoomImage': 'ImagePlotCntlr.ZoomImage', 'PanImage': 'ImagePlotCntlr.recenter', 'StretchImage': 'ImagePlotCntlr.StretchChange', 'CreateRegionLayer': 'DrawLayerCntlr.RegionPlot.createLayer', 'DeleteRegionLayer': 'DrawLayerCntlr.RegionPlot.deleteLayer', 'AddRegionData': 'DrawLayerCntlr.RegionPlot.addRegion', 'RemoveRegionData': 'DrawLayerCntlr.RegionPlot.removeRegion', 'PlotMask': 'ImagePlotCntlr.plotMask', 'DeleteOverlayMask': 'ImagePlotCntlr.deleteOverlayPlot', 'AddCell': 'layout.addCell', 'ShowCoverage': 'layout.enableSpecialViewer', 'ShowImageMetaData': 'layout.enableSpecialViewer', 'ReinitViewer': 'app_data.reinitApp'}

Definition of Firefly action (dict).

ALL = 'ALL_EVENTS_ENABLED'

All events are enabled for the listener (str).

EXTENSION_TYPE = ['AREA_SELECT', 'LINE_SELECT', 'POINT']

Type of plot where the extension is added to (list of str).

LO_VIEW_DICT = {'table': 'tables', 'image': 'images', 'xyPlot': 'xyPlots', 'imageMeta': 'tableImageMeta', 'coverImage': 'coverageImage'}

Definition of layout viewer (dict).

STRETCH_ALGORITHM_DICT = {'linear': 44, 'log': 45, 'loglog': 46, 'equal': 47, 'squared': 48, 'sqrt': 49, 'asinh': 50, 'powerlaw_gamma': 51}

Definition of stretch algorithm (dict).

STRETCH_TYPE_DICT = {'percent': 88, 'minmax': 89, 'absolute': 90, 'zscale': 91, 'sigma': 92}

Definition of stretch type (dict).

Methods Documentation

add_cell(row, col, width, height, element_type, cell_id=None)

Add a slate viewer cell.

Parameters:

row : int

Cell row position.

col : int

Cell column position.

width : int

Cell horizontal size.

height : int

Cell vertical size.

element_type : {‘tables’, ‘images’, ‘xyPlots’, ‘tableImageMeta’, ‘coverageImage’}

Cell element type. Use ‘xyPlots’ for histograms.

cell_id : str, optional

Cell Id.

Returns:

out : dict

Status of the request, like {‘success’: True, ‘cell_id’: ‘Cell-1’}.

add_extension(ext_type, plot_id=None, title='', tool_tip='', extension_id=None, image_src=None)

Add an extension to the plot. Extensions are context menus that allows you to extend what Firefly can do when certain actions happen.

Parameters:

ext_type : {‘AREA_SELECT’, ‘LINE_SELECT’, ‘POINT’}

Extension type. It can be one of the values in the list or any Firefly action, or it will be reset to be ‘NONE’.

plot_id : str, optional

Plot ID of the plot which the extension is added to, if not specified, this request is applied to all plots in the same group of the active plot.

title : str, optional

The title for the extension.

tool_tip : str, optional

Tooltip for the extension.

extension_id : str, optional

Extension ID. It will be created automatically if not specifed.

image_src : str, optional

Image source of an icon to be displayed on the toolbar instead of the title. Image source could be an image path or an image url.

Returns:

out : dict

Status of the request, like {‘success’: True}.

Note

If image_src is not specified, then no extension is added.

add_listener(callback, name='ALL_EVENTS_ENABLED')

Add a callback function to listen for events on the Firefly client.

Parameters:

callback : Function

The function to be called when a event happens on the Firefly client.

name : str, optional

The name of the events (the default is ALL, all events).

Returns:

out : none

add_mask(bit_number, image_number, plot_id, mask_id=None, color=None, title=None, file_on_server=None)

Add a mask layer.

Parameters:

bit_number : int

Bit number of the mask to overlay.

image_number : int

Image number of the mask layer HDU extension in FITS. This is a zero-based index.

plot_id : str

ID of the plot to overlay the mask on.

mask_id : str, optional

Mask ID. It will be created automatically if not specified.

color : str, optional

Color as an html color (eg. ‘#ff0000’(red), ‘#00ff00’ (green)). A color will be created in default if not specified.

title : str, optional

Title of the mask layer.

file_on_server : str, optional

File to get the mask from. The mask will be taken from the original file if not specified.

Returns:

out : dict

Status of the request, like {‘success’: True}.

add_region_data(region_data, region_layer_id, title=None, plot_id=None)

Add region entries to a region layer with the given ID.

Parameters:

region_data : str or list of str

Region entries to be added.

region_layer_id : str

ID of region layer where the entries are added to.

title : str, optional

Title of the region layer. If the layer exists, the original title is replaced. If the layer doesn’t exist, a new layer with the given title is created.

plot_id : str or list of str, optional

Plot ID. This is for the case that the region layer doesn’t exist. If the region layer exists, this request applies to all plots attached to the layer.

Returns:

out : dict

Status of the request, like {‘success’: True}.

Note

If no region layer with the given ID exists, a new region layer will be created

automatically just like how function overlay_region_layer works.

static create_image_url(image_source)

Create image url or data uri according to the image source.

Parameters:

image_source : str

An image path or image url.

Returns:

out : str

Data URI or image url.

delete_region_layer(region_layer_id, plot_id=None)

Delete region layer from the loaded FITS images.

Parameters:

region_layer_id : str

Region layer ID. The region layer with the region layer ID is to be removed.

plot_id : str or a list of str, optional

Plot ID. The region layer is removed from the plot with the plot ID. If not specified, then remove region layer from all plots in the same group of the active plot.

Returns:

out : dict

Status of the request, like {‘success’: True}.

disconnect()

Disconnect the WebSocket.

dispatch_remote_action(channel, action_type, payload)

Dispatch the action to the server by using ‘GET’ request.

Parameters:

channel : str

WebSocket channel ID.

action_type : str

Action type, one of actions from FireflyClient’s attribute, ACTION_DICT.

payload : dict

Payload, the content varies based on the value of action_type.

Returns:

out : dict

Status of remote dispatch, like {‘success’: True}.

dispatch_remote_action_by_post(channel, action_type, payload)

Dispatch the action to the server by using ‘POST’ request.

Parameters:

channel : str

Websocket channel ID.

action_type : str

Action type, one of actions from FireflyClient’s attribute, ACTION_DICT.

payload : dict

Payload, the content varies based on the value of action_type.

Returns:

out : dict

Status of remotely dispatch, like {‘success’: True}.

fetch_table(file_on_server, tbl_id=None, page_size=1)

Fetch table data without showing them

Parameters:

file_on_server : str

The name of the file on the server. If you use upload_file(), then it is the return value of the method. Otherwise it is a file that Firefly has direct access to.

tbl_id : str, optional

A table ID. It will be created automatically if not specified.

page_size : int, optional

The number of rows to fetch.

Returns:

out : dict

Status of the request, like {‘success’: True}.

get_firefly_url(mode='minimal', channel=None)

Get URL to Firefly Tools viewer and the channel set. Normally this method will be called without any parameters.

Parameters:

mode : {‘full’, ‘minimal’}, optional

Url mode (the default is ‘minimal’).

channel : str, optional

A different channel string than the default.

Returns:

out : str

url string.

launch_browser(url=None, channel=None, force=False)

Launch a browser with the Firefly Tools viewer and the channel set.

The page is launched when force is True or the page is not opened yet. Normally this method will be called without any parameters.

Parameters:

url : str, optional

An url overriding the default (the default is set as self.url_bw).

channel : str, optional

A different channel than the default (the default is set as self.channel).

force : bool, optional

If the browser page is forced to be opened (the default is False).

Returns:

out : str

The channel ID.

overlay_region_layer(file_on_server=None, region_data=None, title=None, region_layer_id=None, plot_id=None)

Overlay a region layer on the loaded FITS images. The regions are defined either by a file or by text region description.

Parameters:

file_on_server : str, optional

This is the name of the file on the server. If you use upload_file(), then it is the return value of the method. Otherwise it is a file that Firefly has direct read access to.

region_data : str or list of str, optional

Region description, either a list of strings or a string.

title : str, optional

Title of the region layer.

region_layer_id : str, optional

ID of the region layer to be created. It is automatically created if not specified.

plot_id : str or list of str, optional

ID of the plot that the region layer is created on. If None, then overlay region(s) on all plots in the same group of the active plot.

Returns:

out : dict

Status of the request, like {‘success’: True}.

Note

file_on_server and region_data are exclusively required.

If both are specified, file_on_server takes the priority. If none is specified, no region layer is created.

received_message(m)

Override the superclass’s method

reinit_viewer()

re-initialize the viewer

Returns:

out : dict

Status of the request, like {‘success’: True}.

remove_listener(callback, name='ALL_EVENTS_ENABLED')

Remove an event name from the callback listener.

Parameters:

callback : Function

A previously set callback function.

name : str, optional

The name of the event to be removed from the callback listener (the default is ALL, all events).

Returns:

out : none

Note

callback in listener list is removed if all events are removed from the callback.

remove_mask(plot_id, mask_id)

Remove a mask layer from the plot with the given plot ID.

Parameters:

plot_id : str

ID of the plot where the mask layer to be removed from.

mask_id : str

ID of the mask layer to be removed.

Returns:

out : dict

Status of the request, like {‘success’: True}

remove_region_data(region_data, region_layer_id)

Remove region entries from a region layer with the give ID.

Parameters:

region_data : str or list of str

Region entries to be removed.

region_layer_id : str

ID of the region layer where the region entries are removed from.

Returns:

out : dict

Status of the request, like {‘success’: True}.

set_pan(plot_id, x=None, y=None, coord='image')

Relocate the image to center on the given image coordinate or EQ_J2000 coordinate. If no (x, y) is given, the image is re-centered at the center of the image.

Parameters:

plot_id : str or list of str

ID of the plot to be panned. If plot_id is a list or tuple, then each plot in the list or the tuple is panned in order.

x, y : int or float, optional

New center of x and y position to scroll to.

coord : {‘image’, ‘J2000’}, optional

Coordinate system (the default is ‘image’).

Returns:

out : dict

Status of the request, like {‘success’: True}.

set_stretch(plot_id, stype=None, algorithm=None, **additional_params)

Change the stretch of the image (no band case).

Parameters:

plot_id : str or list of str

ID of the plot to be stretched. If plot_id is a list or tuple, then each plot in the list or the tuple is stretched in order.

stype : {‘percent’,’minmax’,’absolute’,’zscale’, ‘sigma’}, optional

Stretch method (the default is ‘percent’).

algorithm : {‘linear’, ‘log’,’loglog’,’equal’, ‘squared’, ‘sqrt’, ‘asinh’, ‘powerlaw_gamma’}, optional

Stretch algorithm (the default is ‘linear’).

**additional_params : optional keyword arguments

Parameters for changing the stretch. The options are shown as below:

zscale_contrast : int or float, optional

zscale contrast (the default is 25).

zscale_samples : int, optional

zscale samples, int (the default is 600).

zscale_samples_perline : int, optional

zscale samples per line (the default is 120).

lower_value : int or float, optional

Lower end of stretch (the default is 1).

upper_value : int or float, optional

Upper end of stretch (the default is 90).

Returns:

out : dict

Status of the request, like {‘success’: True}.

Note

zscale_contrast, zscale_samples, and zscale_samples_perline are used when

stype is ‘zscale’, and lower_value and upper_value are used when stype is not ‘zscale’.

set_zoom(plot_id, factor=1.0)

Zoom the image.

Parameters:

plot_id : str or list of str

ID of the plot to be zoomed. If plot_id is a list or tuple, then each plot in the list or the tuple is zoomed in order.

factor : int or float, optional

Zoom factor for the image.

Returns:

out : dict

Status of the request, like {‘success’: True}.

show_chart(group_id=None, **chart_params)

Show a plot.ly chart

Plotly chart is described by a list of trace data and a layout. Any list in trace data can come from a table.

For example, if a trace is defined by {‘tbl_id’: ‘wise’, ‘x’: ‘tables::w1mpro’, ‘y’: ‘tables::w2mpro’ }, x and y points of the trace will come from w1mpro and w2mpro columns of the table with the id wise.

See plotly.js attribute reference for the supported trace types and attributes. Note, that data and layout are expected to be basic Python object hierarchies, as json.dumps is used to convert them to JSON.

Parameters:

group_id : str, optional

Group ID of the chart group where the chart belongs to. If grid view is used, group id is the cell id of the cell which contains the chart.

**chart_params : optional keyword arguments

Parameters for the chart. The options are shown as below:

chartId: str, optional

The chart ID.

data: list of dict, optional

A list of data for all traces of the plot.ly chart. Firefly-specific keys: tbl_id, firefly (for Firefly chart types).

layout: dict, optional

The layout for plot.ly layout. Optional firefly key refers to the information processed by Firefly.

Returns:

out : dict

Status of the request, like {‘success’: True}.

show_coverage(viewer_id=None, table_group='main')

Show image coverage associated with the active table in the specified table group

Parameters:

viewer_id : str, optional

Viewer id, the cell id of the cell which contains the coverage image.

table_group : str, optional

Table group which the image coverage associated table belongs to.

Returns:

out : dict

Status of the request, like {‘success’: True}

show_fits(file_on_server=None, plot_id=None, viewer_id=None, **additional_params)

Show a FITS image.

Parameters:

file_on_server : str, optional

The is the name of the file on the server. If you use upload_file(), then it is the return value of the method. Otherwise it is a file that Firefly has direct access to.

plot_id : str, optional

The ID you assign to the image plot. This is necessary to further control the plot.

viewer_id : str, optional

The ID you assign to the viewer (or cell) used to contain the image plot. If grid view is used for display, the viewer id is the cell id of the cell which contains the image plot.

**additional_params : optional keyword arguments

Any valid fits viewer plotting parameter, please see the details in fits plotting parameters.

More options are shown as below:

MultiImageIdx : int, optional

Display only a particular image extension from the file (zero-based index).

Title : str, optional

Title to display with the image.

Returns:

out : dict

Status of the request, like {‘success’: True}.

Note

Either file_on_server or the target information set by addition_parameters

is used for fits search.

show_fits_3color(three_color_params, plot_id=None, viewer_id=None)

Show a FITS image by giving the three color requirement

Parameters:

three_color_params : list of dict or dict

A list or objects contains fits viewer plotting parameters for either all bands or one single band. For valid fits viewer plotting parameter, please see the details in fits plotting parameters or the description of **additional_params in function show_fits.

plot_id : str, optional

The ID you assign to the image plot. This is necessary to further control the plot.

viewer_id : str, optional

The ID you assign to the viewer (or cell) used to contain the image plot. If grid view is used for display, the viewer id is the cell id of the cell which contains the image plot.

Returns:

out : dict

Status of the request, like {‘success’: True}.

show_histogram(tbl_id, group_id=None, **histogram_params)

Show a histogram

Parameters:

tbl_id : str

A table ID of the data to be plotted.

group_id : str, optional

Group ID of the chart group where the histogram belongs to. If grid view is used, group id is the cell id of the cell which contains the histogram.

**histogram_params : optional keyword arguments

Parameters for histogram. The options are shown as below:

col: str

Column or expression to use for x values, can contain multiple column names, ex. log(col) or (col1-col2)/col3.

xOptions: str

comma separated list of x axis options: flip,log.

yOptions: str

comma separated list of y axis options: flip,log.

falsePositiveRate: int or float

false positive rate for bayesian blocks algorithm.

numBins : int

Number of bins for fixed bins algorithm, default is 50.

binWidth : int or float

Bin width.

Returns:

out : dict

Status of the request, like {‘success’: True}.

Note

For the histogram parameters, col is required.

show_image_metadata(viewer_id=None, table_group='main')

Show the image associated with the active (image metadata) table in the specified table group

Parameters:

viewer_id : str, optional

Viewer id, the cell id of the cell which contains the image from image metadata table.

table_group : str, optional

Table group which the image metadata table belongs to.

Returns:

out : dict

Status of the request, like {‘success’: True}

show_table(file_on_server=None, tbl_id=None, title=None, page_size=100, is_catalog=True, meta=None, target_search_info=None, options=None)

Show a table.

Parameters:

file_on_server : str

The name of the file on the server. If you use upload_file(), then it is the return value of the method. Otherwise it is a file that Firefly has direct access to.

tbl_id : str, optional

A table ID. It will be created automatically if not specified.

title : str, optional

Title associated with the table.

page_size : int, optional

The number of rows that are shown in the table page (the default is 100).

is_catalog : bool, optional

If the table file is a catalog (the default is True) or not.

meta : dict

META_INFO for the table search request.

target_search_info : dict, optional

The information for target search, it may contain the following fields:

catalogProject : str

Catalog project, such as ‘WISE’.

catalog : str

Table to be searched, such as ‘allwise_p3as_psd’.

use : str

Usage of the table search, such as ‘catalog_overlay’.

position : str

Target position, such as ‘10.68479;41.26906;EQ_J2000’.

SearchMethod : {‘Cone’, ‘Eliptical’, ‘Box’, ‘Polygon’, ‘Table’, ‘AllSky’}

Target search method.

radius : float

The radius for ‘Cone’ or the semi-major axis for ‘Eliptical’ search in terms of unit arcsec.

posang : float

Position angle for ‘Elipitical’ search in terms of unit arcsec.

ratio : float

Axial ratio for ‘Elipital’ search.

size : float

Side size for ‘Box’ search in terms of unit arcsec.

polygon : str

ra/dec of polygon corners, such as ‘ra1, dec1, ra2, dec2,... raN, decN’.

filename : str

The name of file on server on multi-objects for ‘Table’ search.

options : dict, optional

Containing parameters for table display, such as,

removable : bool

if table is removable.

showUnits : bool

if table shows units for the columns.

showFilters : bool

if table shows filter button

Returns:

out : dict

Status of the request, like {‘success’: True}.

Note

file_on_server and target_search_info are exclusively required.

show_xyplot(tbl_id, standalone=False, group_id=None, **chart_params)

Show a XY plot

Parameters:

tbl_id : str

A table ID of the data to be plotted.

standalone : bool, optional

When it is True, the chart is always present in the chart area, no matter if the related table is present or not.

group_id : str, optional

Group ID of the chart group where the chart belongs to. If grid view is used, group id is the cell id of the cell which contains the chart.

**chart_params : optional keyword arguments

Parameters for XY Plot. The options are shown as below:

xCol: str

Column or expression to use for x values, can contain multiple column names, ex. log(col) or (col1-col2)/col3.

xError: str

Column or expression to use for x error, can contain multiple column names

yCol: str

Column or expression to use for y values, can contain multiple column names, ex. sin(col) or (col1-col2)/col3.

yError: str

Column or expression to use for x error, can contain multiple column names.

xyRatio : int or float

Aspect ratio (must be between 1 and 10).

stretch : {‘fit’, ‘fill’}

Stretch method.

xLabel : str

Label to use with x axis.

yLabel : str

Label to use with y axis.

xUnit : str

Unit for x axis.

yUnit : str

Unit for y axis.

xOptions : str

Comma separated list of x axis options: grid,flip,log.

yOptions : str

Comma separated list of y axis options: grid,flip,log.

Returns:

out : dict

Status of the request, like {‘success’: True}.

Note

For the chart parameters, xCol and yCol are required, then all other

parameters are valid.

stay_connected()

Keep WebSocket connected.

upload_data(stream, data_type)

Upload a file like object to the Firefly server. The method should allow either FITS or non-FITS file like data to be streamed without using an actual file.

Parameters:

stream : object

A file like object containing FITS data or others.

data_type : {‘FITS’, ‘UNKNOWN’}

Data type, FITS or others.

Returns:

out : dict

Status, like {‘success’: True}.

upload_file(path, pre_load=True)

Upload a file to the Firefly Server.

Parameters:

path : str

Path of uploaded file. It can be fits, region, and various types of table files.

pre_load : bool, optional

This parameter is not used.

Returns:

out: str

Path of file after the upload.

Note

‘pre_load’ is not implemented in the server (will be removed later).

upload_fits_data(stream)

Upload a FITS file like object to the Firefly server. The method should allow file like data to be streamed without using an actual file.

Parameters:

stream : object

A FITS file like object containing fits data, such as if f = open(<a_fits_path>), f is a file object.

Returns:

out : dict

Status, like {‘success’: True}.

upload_text_data(stream)

Upload a text file like object to the Firefly server. The method should allow text file like data to be streamed without using an actual file.

Parameters:

stream : object

A text file like object containing text data, such as if f = open(<a_textfile_path>), f is a file object.

Returns:

out : dict

Status, like {‘success’: True}.

wait_for_events()

Wait over events from the server.

Pause and do not exit.

This is optional. You should not use this method in ipython notebook. Event will get called anyway.