FireflyClient¶

class firefly_client.FireflyClient(url='http://localhost:8080/firefly', channel=None, html_file='', make_default=False, use_lab_env=False, start_tab=False, start_browser_tab=False, token=None)¶

Bases: ws4py.client.threadedclient.WebSocketClient

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

Parameters:

url : str: URL for Firefly server, e.g. https://lsst-demo.ncsa.illinois.edu/firefly. Defaults to the value of the environment variable FIREFLY_URL, if defined; or to ‘http://localhost:8080/firefly’ if FIREFLY_URL is not defined.
channel : str: WebSocket channel ID. Default is None which auto-generates a unique string.
html_file : str: HTML file that is the ‘landing page’ for users, appended to the URL. e.g. ‘slate.html’. Defaults to None which is an empty string.
make_default : bool: If True, make this the default FireflyClient instance. Default False.
use_lab_env : bool: If True, try to use environment variables for Jupyterlab. This can only be True in the Jupyter lab environment, otherwise there is an error. Default False.
start_tab: `bool`: If True, bring up a Jupyterlab or a browser tab for Firefly. Default False.
start_browser_tab: `bool`: If True, and start_tab is true and in use_lab_env is true then start a browser tab. Default False.
token: `str` or None: A token for connecting to a Firefly server that requires authentication. The provided token will be appended to the string “Bearer ” to form the value of the “Authorization” header in the sessions attribute.

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`).
`INVERSE_STRETCH_ALGORITHM`
`INVERSE_STRETCH_TYPE`
`LO_VIEW_DICT`	Definition of layout viewer (`dict`).
`STRETCH_ALGORITHM_DICT`	Definition of stretch algorithm (`dict`).
`STRETCH_TYPE_DICT`	Definition of stretch type (`dict`).
`bind_addr`	Returns the Unix socket path if or a tuple `(host, port)` depending on the initial URL’s scheme.
`connection`
`daemon`	`True` if the client’s thread is set to be a daemon thread.
`handshake_headers`	List of headers appropriate for the upgrade handshake.
`handshake_request`	Prepare the request to be sent for the upgrade handshake.
`instances`
`local_address`	Local endpoint address as a tuple
`peer_address`	Peer endpoint address as a tuple
`terminated`	Returns `True` if both the client and server have been marked as terminated.

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.
`close`([code, reason])	Initiate the closing handshake with the server.
`close_connection`()	Shutdowns then closes the underlying connection.
`closed`(code[, reason])	Called when the websocket stream and connection are finally closed.
`connect`()	Connects this websocket and starts the upgrade handshake with the remote endpoint.
`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`(action_type, payload[, …])	Dispatch the action to the server by using ‘POST’ request.
`display_url`([url])	Display URL in a user-friendly format
`fetch_table`(file_on_server[, tbl_id, title, …])	Fetch table data without showing them
`get_default_instance`()	Return the default instance
`get_firefly_url`([channel])	Get URL to Firefly Tools viewer and the channel set.
`get_instances`()	Get all current instances
`handshake_ok`()	Called when the upgrade handshake has completed successfully.
`launch_browser`([channel, force, verbose])	Launch a browser with the Firefly Tools viewer and the channel set.
`make_client`([url, html_file, …])	Factory method to create a Firefly client in a plain Python, IPython, or notebook session, and attempt to open a display.
`make_lab_client`([start_browser_tab, …])	Factory method to create a Firefly client in the Jupyterlab environment.
`once`()	Performs the operation of reading from the underlying connection in order to feed the stream of bytes.
`opened`()	Called by the server when the upgrade handshake has succeeded.
`overlay_footprints`(footprint_file[, …])	Overlay a footprint dictionary on displayed images.
`overlay_region_layer`([file_on_server, …])	Overlay a region layer on the loaded FITS images.
`parse_rvstring`(rvstring)	parse a Firefly RangeValues string into a dictionary
`ping`(message)	Send a ping message to the remote peer.
`ponged`(pong)	Pong message, as a `messaging.PongControlMessage` instance, received on the stream.
`process`(bytes)	Takes some bytes and process them through the internal stream’s parser.
`process_handshake_header`(headers)	Read the upgrade handshake’s response headers and validate them against RFC 6455.
`process_response_line`(response_line)	Ensure that we received a HTTP `101` status code in response to our request and if not raises `HandshakeError`.
`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.
`run`()	Performs the operation of reading from the underlying connection in order to feed the stream of bytes.
`run_forever`()	Simply blocks the thread until the websocket has terminated.
`rvstring_from_dict`(rvdict)	create an rvstring from a dictionary
`send`(payload[, binary])	Sends the given `payload` out.
`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, band])	Change the stretch of the image (no band or 3-color per-band cases).
`set_stretch_hprgb`(plot_id[, asinh_q_value, …])	Change the stretch of RGB image (hue-preserving rgb 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 3-color image constructed from the three color parameters
`show_hips`([plot_id, viewer_id, …])	Show HiPS image.
`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_image_or_hips`([plot_id, viewer_id, …])	Show a FiTS or HiPS image.
`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.
`terminate`()	Completes the websocket by calling the `closed` method either using the received closing code and reason, or when none was received, using the special `1006` code.
`unhandled_error`(error)	Called whenever a socket, or an OS, error is trapped by ws4py but not managed by it.
`upload_data`(stream, data_type)	Upload a file like object to the Firefly server.
`upload_file`(path)	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 = {'AddCell': 'layout.addCell', 'AddExtension': 'ExternalAccessCntlr/extensionAdd', 'AddRegionData': 'DrawLayerCntlr.RegionPlot.addRegion', 'CreateRegionLayer': 'DrawLayerCntlr.RegionPlot.createLayer', 'DeleteOverlayMask': 'ImagePlotCntlr.deleteOverlayPlot', 'DeleteRegionLayer': 'DrawLayerCntlr.RegionPlot.deleteLayer', 'FetchTable': 'table.fetch', 'ImagelineBasedFootprint': 'DrawLayerCntlr.ImageLineBasedFP.imagelineBasedFPCreate', 'PanImage': 'ImagePlotCntlr.recenter', 'PlotMask': 'ImagePlotCntlr.plotMask', 'ReinitViewer': 'app_data.reinitApp', 'RemoveRegionData': 'DrawLayerCntlr.RegionPlot.removeRegion', 'ShowCoverage': 'layout.enableSpecialViewer', 'ShowFits': 'ImagePlotCntlr.PlotImage', 'ShowHiPS': 'ImagePlotCntlr.PlotHiPS', 'ShowImageMetaData': 'layout.enableSpecialViewer', 'ShowImageOrHiPS': 'ImagePlotCntlr.plotHiPSOrImage', 'ShowPlot': 'charts.data/chartAdd', 'ShowTable': 'table.search', 'ShowXYPlot': 'charts.data/chartAdd', 'StartBrowserTab': 'StartBrowserTab', 'StartLabWindow': 'StartLabWindow', 'StretchImage': 'ImagePlotCntlr.StretchChange', 'ZoomImage': 'ImagePlotCntlr.ZoomImage'}¶: 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).

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

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

LO_VIEW_DICT = {'coverImage': 'coverageImage', 'image': 'images', 'imageMeta': 'tableImageMeta', 'table': 'tables', 'xyPlot': 'xyPlots'}¶: Definition of layout viewer (dict).

STRETCH_ALGORITHM_DICT = {'asinh': 50, 'equal': 47, 'linear': 44, 'log': 45, 'loglog': 46, 'powerlaw_gamma': 51, 'sqrt': 49, 'squared': 48}¶: Definition of stretch algorithm (dict).

STRETCH_TYPE_DICT = {'absolute': 90, 'minmax': 89, 'percent': 88, 'sigma': 92, 'zscale': 91}¶: Definition of stretch type (dict).

bind_addr¶: Returns the Unix socket path if or a tuple (host, port) depending on the initial URL’s scheme.

connection¶

daemon¶: True if the client’s thread is set to be a daemon thread.

handshake_headers¶: List of headers appropriate for the upgrade handshake.

handshake_request¶: Prepare the request to be sent for the upgrade handshake.

instances = []¶

local_address¶: Local endpoint address as a tuple

peer_address¶: Peer endpoint address as a tuple

terminated¶: Returns True if both the client and server have been marked as terminated.

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.

close(code=1000, reason='')¶: Initiate the closing handshake with the server.

close_connection()¶: Shutdowns then closes the underlying connection.

closed(code, reason=None)¶: Called when the websocket stream and connection are finally closed. The provided code is status set by the other point and reason is a human readable message.

See also

Defined Status Codes http://tools.ietf.org/html/rfc6455#section-7.4.1

connect()¶: Connects this websocket and starts the upgrade handshake with the remote endpoint.

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(action_type, payload, override_channel=None)¶

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

Parameters:	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`. override_channel : `str` overrides the default channel
Returns:	out : `dict` Status of remotely dispatch, like {‘success’: True}.

display_url(url=None)¶

Display URL in a user-friendly format

Parameters:	url : `str`, optional A url overriding the default (the default retrieves from self.get_firefly_url).

fetch_table(file_on_server, tbl_id=None, title=None, page_size=1, table_index=None, meta=None)¶

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.
title : str, optional: Title associated with the table.
page_size : int, optional: The number of rows to fetch.
table_index : int, optional: The table to be fetched in case file_on_server contains multiple tables. It is the extension number for a FITS file or the table index for a VOTable file. In unspeficied, the server will fetch extension 1 from a FITS file or the table at index 0 from a VOTable file.
meta : dict: META_INFO for the table search request.

Returns:

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

classmethod get_default_instance()¶

Return the default instance

Returns:	`FireflyClient` or None Return the first FireflyClient instance, or None if there are none

get_firefly_url(channel=None)¶

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

Parameters:	channel : `str`, optional A different channel string than the default.
Returns:	out : `str` url string.

classmethod get_instances()¶

Get all current instances

Returns:	`list` list of instances

handshake_ok()¶

Called when the upgrade handshake has completed successfully.

Starts the client’s thread.

launch_browser(channel=None, force=False, verbose=True)¶

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:	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). verbose: `bool`, optional If True, print instructions if web browser is not opened (default True)
Returns:	open_success : `bool` If True, the web browser open was successful. url : `str` The URL that is used in the user’s web browser.

static make_client(url='http://localhost:8080/firefly', html_file='', launch_browser=True, channel_override=None, verbose=False, token=None)¶

Factory method to create a Firefly client in a plain Python, IPython, or notebook session, and attempt to open a display. If a display cannot be opened, a link will be displayed.

Parameters:

url : str, optional: URL of the Firefly server. The default is determined by checking environment variables ‘fireflyURLLab’ and ‘FIREFLY_URL’; if these are undefined, then the default is ‘http://localhost:8080/firefly’ for the case of a user running a Firefly server on their desktop.
html_file : str, optional: HTML file that is the ‘landing page’ for users, appended to the URL. The default is the value of the environment variable ‘FIREFLY_HTML’ if it is defined; otherwise None.
launch_browser : bool, optional: If True, attempt to launch a browser tab for the Firefly viewer. If that attempt is unsuccessful, a link for the Firefly viewer is displayed.
channel_override: `str` or None: If channel_override is None, the value of the environment variable ‘FIREFLY_CHANNEL’ is checked. If unset, then a URL-safe channel string is generated. If channel_override is set to a string, it is used for the Firefly channel.
token: `str` or None: A token for connecting to a Firefly server that requires authentication. The provided token will be appended to the string “Bearer ” to form the value of the “Authorization” header in the sessions attribute.

Returns:

fc : FireflyClient: A FireflyClient that works in the lab environment

static make_lab_client(start_browser_tab=False, html_file='', start_tab=True, verbose=False, token=None)¶

Factory method to create a Firefly client in the Jupyterlab environment. If you are using Jupyterlab with the jupyter_firefly_extension installed, then this method is the best way to construct a FireflyClient. If called in a non-Jupyterlab environment, the method raises a RuntimeError.

Parameters:

start_browser_tab : bool: If True start a browser tab, if False start a lab tab. start_tab must also be True. To start a new tab you will have to disable popup blocking for the Jupyterlab site.

Chrome: look at the right side of the address bar Firefox: a preference bar appears at the top Safari: shows an animation to follow on the left side bar
html_file : str, optional: HTML file that is the ‘landing page’ for users, appended to the URL. You should almost always take the default, e.g. ‘slate.html’. Defaults to the value of the environment variable ‘FIREFLY_URL’ if it is defined: otherwise defaults to None.
start_tab : bool, optional: If True, bring up a Jupyterlab or a browser tab for Firefly. You should almost always take the default.
token: `str` or None: A token for connecting to a Firefly server that requires authentication. The provided token will be appended to the string “Bearer ” to form the value of the “Authorization” header in the sessions attribute.

Returns:

out : FireflyClient: A FireflyClient that works in the lab environment

once()¶

Performs the operation of reading from the underlying connection in order to feed the stream of bytes.

Because this needs to support SSL sockets, we must always read as much as might be in the socket at any given time, however process expects to have itself called with only a certain number of bytes at a time. That number is found in self.reading_buffer_size, so we read everything into our own buffer, and then from there feed self.process.

Then the stream indicates whatever size must be read from the connection since it knows the frame payload length.

It returns False if an error occurred at the socket level or during the bytes processing. Otherwise, it returns True.

opened()¶: Called by the server when the upgrade handshake has succeeded.

overlay_footprints(footprint_file, footprint_image=None, title=None, footprint_layer_id=None, plot_id=None, table_index=None, **additional_params)¶

Overlay a footprint dictionary on displayed images. The dictionary must be convertible to JSON format.

Parameters:

footprint_file : str

footprint file with a table containing measurements and footprints

footprint_image: `str`

footprint image file

title : str, optional

Title of the footprint layer.

footprint_layer_id : str, optional

ID of the footprint 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 footprint layer is created on. If None, then overlay the footprint on all plots in the same group of the active plot.

table_index : int, optional

The table to be shown in case file_on_server contains multiple tables. It is the extension number for a FITS file or the table index for a VOTable file. In unspeficied, the server will fetch extension 1 from a FITS file or the table at index 0 from a VOTable file.

**additional_params : optional keyword arguments

parameters for footprint overlays, the options are shown as below:

color : str, optional: color for the footprint. it is color name like ‘red’ or color code like ‘rgb(0,0,0)’
style : str, optional: footprint display style, ‘outline’ or ‘fill’
showText : bool, optional: show text, footprint id if there is, by the ‘outline’ display
selectColor : ‘str`, optional: color for selected footprint
highlightColor : str optional: color for highlighted footprint

Returns:

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

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.

parse_rvstring(rvstring)¶

parse a Firefly RangeValues string into a dictionary

Parameters:	rvstring : `str` RangeValues string as returned by the set_stretch method.
Returns:	outdict : `dict` dictionary of the inputs

ping(message)¶: Send a ping message to the remote peer. The given message must be a unicode string.

ponged(pong)¶: Pong message, as a messaging.PongControlMessage instance, received on the stream.

process(bytes)¶

Takes some bytes and process them through the internal stream’s parser. If a message of any kind is found, performs one of these actions:

A closing message will initiate the closing handshake
Errors will initiate a closing handshake
A message will be passed to the received_message method
Pings will see pongs be sent automatically
Pongs will be passed to the ponged method

The process should be terminated when this method returns False.

process_handshake_header(headers)¶: Read the upgrade handshake’s response headers and validate them against RFC 6455.

process_response_line(response_line)¶: Ensure that we received a HTTP 101 status code in response to our request and if not raises HandshakeError.

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}.

run()¶

Performs the operation of reading from the underlying connection in order to feed the stream of bytes.

We start with a small size of two bytes to be read from the connection so that we can quickly parse an incoming frame header. Then the stream indicates whatever size must be read from the connection since it knows the frame payload length.

Note that we perform some automatic opererations:

On a closing message, we respond with a closing message and finally close the connection
We respond to pings with pong messages.
Whenever an error is raised by the stream parsing, we initiate the closing of the connection with the appropiate error code.

This method is blocking and should likely be run in a thread.

run_forever()¶: Simply blocks the thread until the websocket has terminated.

rvstring_from_dict(rvdict)¶

create an rvstring from a dictionary

Parameters:	rvdict : `dict` Dictionary with the same keys as those returned by parse_rvstring
Returns:	rvstring : `str` RangeValues string that can be passed to the show_fits methods

send(payload, binary=False)¶

Sends the given payload out.

If payload is some bytes or a bytearray, then it is sent as a single message not fragmented.

If payload is a generator, each chunk is sent as part of fragmented message.

If binary is set, handles the payload as a binary message.

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, band=None, **additional_params)¶

Change the stretch of the image (no band or 3-color per-band cases).

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’).

band : {‘RED’, ‘GREEN’, ‘BLUE’, ‘ALL’}, optional

3-color band to apply stretch to

**additional_params : optional keyword arguments

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

zscale_contrast : int, 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).
asinh_q_value : float, optional: The asinh softening parameter for Asinh stretch. Use Q=0 for linear stretch, increase Q to make brighter features visible. When not specified, Q is calculated by Firefly to use full color range.
gamma_value: The gamma value for Power Law Gamma stretch

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_stretch_hprgb(plot_id, asinh_q_value=None, scaling_k=1.0, pedestal_value=1, pedestal_type='percent')¶

Change the stretch of RGB image (hue-preserving rgb case). When a parameter is a list, it must contain three elements, for red, green and blue bands respectively. Otherwise the parameter is a scalar that is used for all three bands.

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.
asinh_q_value : float, optional: The asinh softening parameter for Asinh stretch. Use Q=0 for linear stretch, increase Q to make brighter features visible. When not specified, Q is calculated by Firefly to use full color range for intensity.
scaling_k : float or list of float, optional: Scaling coefficient from 0.1 to 10 (the default is 1).
pedestal_type : {‘percent’, ‘minmax’, ‘absolute’, ‘zscale’, ‘sigma’} or list of str, optional: Method to obtain pedestal value (the default is ‘percent’).
pedestal_value : float or list of float, optional: Minimum value (the default is 1 percent).

Returns:

out : dict: Status of the request, like {‘success’: True}.
.. note:: `pedestal_value` is used when `pedestal_type` 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 `additional_params`: is used for image search.

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

Show a 3-color image constructed from the three color parameters

Parameters:

three_color_params : list of dict or dict: A list or objects contains image viewer plotting parameters for either all bands or one single band. For valid image 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_hips(plot_id=None, viewer_id=None, hips_root_url=None, hips_image_conversion=None, **additional_params)¶

Show HiPS image.

Parameters:

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.

hips_root_url : str

HiPS access URL

hips_image_conversion: `dict`, optional

The info used to convert between image and HiPS

**additional_params : optional keyword arguments

parameters for HiPS viewer plotting, the options are shown as below:

WorldPt : str, optional: World point as the center of the HiPS, if not defined, then get it from HiPS properties or set as the origin of the celestial coordinates.
Title : str, optional: Title to display with the HiPS.
SizeInDeg : int or float, optional: Field of view for HiPS.

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_image_or_hips(plot_id=None, viewer_id=None, image_request=None, hips_request=None, fov_deg_fallover=0.12, allsky_request=None, plot_allsky_first=False)¶

Show a FiTS or HiPS image.

Parameters:

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.
image_request : dict, optional: Request with fits plotting parameters. For valid fits viewer plotting parameter, please see the the description of show_fits or show_fits_3color.
hips_request : dict, optional: Request with hips plotting parameters. For valid HiPS viewer plotting paramter, please see the description of show_hips.
fov_deg_fallover : float, optional: The size in degrees that the image will switch between hips and a image cutout.
allsky_request : dict, optional: Allsky type request, like {‘Type’: ‘ALL_SKY’}
plot_allsky_first : bool, optional: Plot all sky first If there is an all sky set up.
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, table_index=None, column_spec=None, filters=None, visible=True)¶

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

table_index : int, optional

The table to be shown in case file_on_server contains multiple tables. It is the extension number for a FITS file or the table index for a VOTable file. In unspeficied, the server will fetch extension 1 from a FITS file or the table at index 0 from a VOTable file.

column_spec : str, optional

A string specifying column names from the table that will be shown. Column names must appear in the string in quotes, eg. ‘“ra”,”dec”,”mag”’ It is possible to derive columns, e.g. ‘“flux”/”flux_err” as “SNR”’

filters : str, optional

A string specifying filters. Column names must be quoted. For example, ‘(“coord_dec” > -0.478) and (“parent” > 0)’.

visible: `bool`, optional

If false, only load the table to Firefly but don’t show it in the UI

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.

terminate()¶

Completes the websocket by calling the closed method either using the received closing code and reason, or when none was received, using the special 1006 code.

Finally close the underlying connection for good and cleanup resources by unsetting the environ and stream attributes.

unhandled_error(error)¶

Called whenever a socket, or an OS, error is trapped by ws4py but not managed by it. The given error is an instance of socket.error or OSError.

Note however that application exceptions will not go through this handler. Instead, do make sure you protect your code appropriately in received_message or send.

The default behaviour of this handler is to log the error with a message.

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)¶

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.
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.

Navigation

FireflyClient¶