Add jpg, png, svg image generation (#88)

* Add image download and callback functionality

* Minor updates

* Make api more concise

* Update changelog

* Add JSON

* Revert "Add JSON"

This reverts commit 4fa1fed.

* Compile js and python files

* Compile js and python files (add files this time)

* added example app to test image generation

* modified setup.py to include utils in modified package

* added cytoscape-svg as extension

* extended cytotscape react to enable svg export,added example app to test imageDownload

* renamed buttons in example app

* rebuild it using yarn fixed compound nodes issue

* updated changelog, moved examples into demos/, updated E-mails in package.json

* updated comments in Cytoscape.react.js, added usage-image-export.py based on usage-event.py

* added usage-image-export.py to test_usage

* moved cytoscape-svg into extra_index.js

* resolved code linting issues

* added usage-image-export gif to README

* added random print statement in usage-image-export.py to pass pylint

Co-authored-by: Christian Legaspi <[email protected]>

Author: IvoLeist

.gitignore

@@ -2,10 +2,10 @@
 # Created by .ignore support plugin (hsz.mobi)
 ### VisualStudioCode template
 .vscode/*
-!.vscode/settings.json
-!.vscode/tasks.json
-!.vscode/launch.json
-!.vscode/extensions.json
+.vscode/settings.json
+.vscode/tasks.json
+.vscode/launch.json
+.vscode/extensions.json
 ### JetBrains template
 # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and WebStorm
 # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839

CHANGELOG.md

@@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 * Contributed initial build of R package.
+* Added access to cytoscape.js PNG and JPG image generation API through `generateImage` and
+  `imageData` properties.
+* Added ability to download image files generated with `generateImage` client-side without sending 
+  data to the server.
+* Used the newly added `generateImage` and `imageData` properties to enable svg generation using https://github.com/kinimesi/cytoscape-svg
 
 ### Changed
 * `utils.Tree`: v0.1.1 broke compatibility with Python 2. Therefore, modified code to be compatible

README.md

@@ -128,4 +128,8 @@ The Pull Request and Issue Templates were inspired from the
 [Code](demos/usage-elements-extra.py)
 ![View usage-elements-extra on Github](demos/images/usage-elements-extra.gif)
 
+### Use export graph as image
+[Code](demos/usage-image-export.py)
+![View usage-image-export on Github](demos/images/usage-image-export.gif)
+
 For an extended gallery, visit the [demos' readme](demos/README.md).

dash_cytoscape/Cytoscape.py

@@ -12,8 +12,8 @@ class Cytoscape(Component):
 - id (string; optional): The ID used to identify this component in Dash callbacks.
 - className (string; optional): Sets the class name of the element (the value of an element's html
 class attribute).
-- style (dict; optional): Add inline styles to the root element.
-- elements (list; optional): A list of dictionaries representing the elements of the networks.
+- style (dict; default {width: '600px', height: '600px'}): Add inline styles to the root element.
+- elements (list of dicts; optional): A list of dictionaries representing the elements of the networks.
     1. Each dictionary describes an element, and specifies its purpose.
         - `group` (string): Either 'nodes' or 'edges'. If not given, it's automatically inferred.
         - `data` (dictionary): Element specific data.
@@ -32,7 +32,7 @@ class attribute).
         - `classes` (string): Space separated string of class names of the element. Those classes can be selected by a style selector.
 
     2. The [official Cytoscape.js documentation](http://js.cytoscape.org/#notation/elements-json) offers an extensive overview and examples of element declaration.
-- stylesheet (list; optional): A list of dictionaries representing the styles of the elements.
+- stylesheet (list of dicts; optional): A list of dictionaries representing the styles of the elements.
     1. Each dictionary requires the following keys:
         - `selector` (string): Which elements you are styling. Generally, you select a group of elements (node, edges, both), a class (that you declare in the element dictionary), or an element by ID.
         - `style` (dictionary): What aspects of the elements you want to modify. This could be the size or color of a node, the shape of an edge arrow, or many more.
@@ -42,7 +42,7 @@ class attribute).
     exhaustively documented in the Cytoscape.js docs. Although methods such
     as `cy.elements(...)` and `cy.filter(...)` are not available, the selector
     string syntax stays the same.
-- layout (dict; optional): A dictionary specifying how to set the position of the elements in your
+- layout (dict; default {name: 'grid'}): A dictionary specifying how to set the position of the elements in your
 graph. The `'name'` key is required, and indicates which layout (algorithm) to
 use.
     1. The layouts available by default are:
@@ -80,33 +80,33 @@ class attribute).
     Note that certain keys are not supported in Dash since the value is a
     JavaScript function or a callback. Please visit [this issue](https://github.com/plotly/dash-cytoscape/issues/25)
     for more information.
-- pan (dict; optional): Dictionary indicating the initial panning position of the graph. The
+- pan (dict; default {x: 0, y: 0}): Dictionary indicating the initial panning position of the graph. The
 following keys are accepted:
     - `x` (number): The x-coordinate of the position.
     - `y` (number): The y-coordinate of the position.
-- zoom (number; optional): The initial zoom level of the graph. You can set `minZoom` and
+- zoom (number; default 1): The initial zoom level of the graph. You can set `minZoom` and
 `maxZoom` to set restrictions on the zoom level.
-- panningEnabled (boolean; optional): Whether panning the graph is enabled (i.e., the position of the graph is
+- panningEnabled (boolean; default True): Whether panning the graph is enabled (i.e., the position of the graph is
 mutable overall).
-- userPanningEnabled (boolean; optional): Whether user events (e.g. dragging the graph background) are allowed to
+- userPanningEnabled (boolean; default True): Whether user events (e.g. dragging the graph background) are allowed to
 pan the graph.
-- minZoom (number; optional): A minimum bound on the zoom level of the graph. The viewport can not be
+- minZoom (number; default 1e-50): A minimum bound on the zoom level of the graph. The viewport can not be
 scaled smaller than this zoom level.
-- maxZoom (number; optional): A maximum bound on the zoom level of the graph. The viewport can not be
+- maxZoom (number; default 1e50): A maximum bound on the zoom level of the graph. The viewport can not be
 scaled larger than this zoom level.
-- zoomingEnabled (boolean; optional): Whether zooming the graph is enabled (i.e., the zoom level of the graph
+- zoomingEnabled (boolean; default True): Whether zooming the graph is enabled (i.e., the zoom level of the graph
 is mutable overall).
-- userZoomingEnabled (boolean; optional): Whether user events (e.g. dragging the graph background) are allowed
+- userZoomingEnabled (boolean; default True): Whether user events (e.g. dragging the graph background) are allowed
 to pan the graph.
-- boxSelectionEnabled (boolean; optional): Whether box selection (i.e. drag a box overlay around, and release it
+- boxSelectionEnabled (boolean; default False): Whether box selection (i.e. drag a box overlay around, and release it
 to select) is enabled. If enabled, the user must taphold to pan the graph.
-- autoungrabify (boolean; optional): Whether nodes should be ungrabified (not grabbable by user) by
+- autoungrabify (boolean; default False): Whether nodes should be ungrabified (not grabbable by user) by
 default (if true, overrides individual node state).
-- autolock (boolean; optional): Whether nodes should be locked (not draggable at all) by default
+- autolock (boolean; default False): Whether nodes should be locked (not draggable at all) by default
 (if true, overrides individual node state).
-- autounselectify (boolean; optional): Whether nodes should be unselectified (immutable selection state) by
+- autounselectify (boolean; default False): Whether nodes should be unselectified (immutable selection state) by
 default (if true, overrides individual element state).
-- autoRefreshLayout (boolean; optional): Whether the layout should be refreshed when elements are added or removed.
+- autoRefreshLayout (boolean; default True): Whether the layout should be refreshed when elements are added or removed.
 - tapNode (dict; optional): The complete node dictionary returned when you tap or click it. Read-only.
 
     1. Node-specific items:
@@ -164,14 +164,37 @@ class attribute).
 - selectedNodeData (list; optional): The list of data dictionaries of all selected nodes (e.g. using
 Shift+Click to select multiple nodes, or Shift+Drag to use box selection). Read-only.
 - selectedEdgeData (list; optional): The list of data dictionaries of all selected edges (e.g. using
-Shift+Click to select multiple nodes, or Shift+Drag to use box selection). Read-only."""
+Shift+Click to select multiple nodes, or Shift+Drag to use box selection). Read-only.
+- generateImage (dict; optional): Dictionary specifying options to generate an image of the current cytoscape graph.
+Value is cleared after data is received and image is generated. This property will
+be ignored on the initial creation of the cytoscape object and must be invoked through
+a callback after it has been rendered. The `'type'` key is required.
+The following keys are supported:
+     - `type` (string): File type to ouput of 'svg, 'png', 'jpg', or 'jpeg' (alias of 'jpg')
+     - `options` (dictionary, optional): Dictionary of options to cy.png() / cy.jpg() or cy.svg() for
+         image generation. See http://js.cytoscape.org/#core/export for details.
+         For `'output'`, only 'base64' and 'base64uri' are supported.
+         Default: `{'output': 'base64uri'}`.
+     - `action` (string, optional): Default: `'store'`. Must be one of the following:
+         - `'store'`: Stores the image data (only jpg and png are supported) in `imageData` and invokes
+             server-side Dash callbacks.
+         - `'download'`: Downloads the image as a file with all data handling
+             done client-side. No `imageData` callbacks are fired.
+         - `'both'`: Stores image data and downloads image as file.
+     - `filename` (string, optional): Name for the file to be downloaded. Default: 'cyto'.
+
+If the app does not need the image data server side and/or it will only be used to download
+the image, it may be prudent to invoke `'download'` for `action` instead of
+`'store'` to improve performance by preventing transfer of data to the server.
+- imageData (string; optional): String representation of the image requested with generateImage. Null if no
+image was requested yet or the previous request failed. Read-only."""
     @_explicitize_args
-    def __init__(self, id=Component.UNDEFINED, className=Component.UNDEFINED, style=Component.UNDEFINED, elements=Component.UNDEFINED, stylesheet=Component.UNDEFINED, layout=Component.UNDEFINED, pan=Component.UNDEFINED, zoom=Component.UNDEFINED, panningEnabled=Component.UNDEFINED, userPanningEnabled=Component.UNDEFINED, minZoom=Component.UNDEFINED, maxZoom=Component.UNDEFINED, zoomingEnabled=Component.UNDEFINED, userZoomingEnabled=Component.UNDEFINED, boxSelectionEnabled=Component.UNDEFINED, autoungrabify=Component.UNDEFINED, autolock=Component.UNDEFINED, autounselectify=Component.UNDEFINED, autoRefreshLayout=Component.UNDEFINED, tapNode=Component.UNDEFINED, tapNodeData=Component.UNDEFINED, tapEdge=Component.UNDEFINED, tapEdgeData=Component.UNDEFINED, mouseoverNodeData=Component.UNDEFINED, mouseoverEdgeData=Component.UNDEFINED, selectedNodeData=Component.UNDEFINED, selectedEdgeData=Component.UNDEFINED, **kwargs):
-        self._prop_names = ['id', 'className', 'style', 'elements', 'stylesheet', 'layout', 'pan', 'zoom', 'panningEnabled', 'userPanningEnabled', 'minZoom', 'maxZoom', 'zoomingEnabled', 'userZoomingEnabled', 'boxSelectionEnabled', 'autoungrabify', 'autolock', 'autounselectify', 'autoRefreshLayout', 'tapNode', 'tapNodeData', 'tapEdge', 'tapEdgeData', 'mouseoverNodeData', 'mouseoverEdgeData', 'selectedNodeData', 'selectedEdgeData']
+    def __init__(self, id=Component.UNDEFINED, className=Component.UNDEFINED, style=Component.UNDEFINED, elements=Component.UNDEFINED, stylesheet=Component.UNDEFINED, layout=Component.UNDEFINED, pan=Component.UNDEFINED, zoom=Component.UNDEFINED, panningEnabled=Component.UNDEFINED, userPanningEnabled=Component.UNDEFINED, minZoom=Component.UNDEFINED, maxZoom=Component.UNDEFINED, zoomingEnabled=Component.UNDEFINED, userZoomingEnabled=Component.UNDEFINED, boxSelectionEnabled=Component.UNDEFINED, autoungrabify=Component.UNDEFINED, autolock=Component.UNDEFINED, autounselectify=Component.UNDEFINED, autoRefreshLayout=Component.UNDEFINED, tapNode=Component.UNDEFINED, tapNodeData=Component.UNDEFINED, tapEdge=Component.UNDEFINED, tapEdgeData=Component.UNDEFINED, mouseoverNodeData=Component.UNDEFINED, mouseoverEdgeData=Component.UNDEFINED, selectedNodeData=Component.UNDEFINED, selectedEdgeData=Component.UNDEFINED, generateImage=Component.UNDEFINED, imageData=Component.UNDEFINED, **kwargs):
+        self._prop_names = ['id', 'className', 'style', 'elements', 'stylesheet', 'layout', 'pan', 'zoom', 'panningEnabled', 'userPanningEnabled', 'minZoom', 'maxZoom', 'zoomingEnabled', 'userZoomingEnabled', 'boxSelectionEnabled', 'autoungrabify', 'autolock', 'autounselectify', 'autoRefreshLayout', 'tapNode', 'tapNodeData', 'tapEdge', 'tapEdgeData', 'mouseoverNodeData', 'mouseoverEdgeData', 'selectedNodeData', 'selectedEdgeData', 'generateImage', 'imageData']
         self._type = 'Cytoscape'
         self._namespace = 'dash_cytoscape'
         self._valid_wildcard_attributes =            []
-        self.available_properties = ['id', 'className', 'style', 'elements', 'stylesheet', 'layout', 'pan', 'zoom', 'panningEnabled', 'userPanningEnabled', 'minZoom', 'maxZoom', 'zoomingEnabled', 'userZoomingEnabled', 'boxSelectionEnabled', 'autoungrabify', 'autolock', 'autounselectify', 'autoRefreshLayout', 'tapNode', 'tapNodeData', 'tapEdge', 'tapEdgeData', 'mouseoverNodeData', 'mouseoverEdgeData', 'selectedNodeData', 'selectedEdgeData']
+        self.available_properties = ['id', 'className', 'style', 'elements', 'stylesheet', 'layout', 'pan', 'zoom', 'panningEnabled', 'userPanningEnabled', 'minZoom', 'maxZoom', 'zoomingEnabled', 'userZoomingEnabled', 'boxSelectionEnabled', 'autoungrabify', 'autolock', 'autounselectify', 'autoRefreshLayout', 'tapNode', 'tapNodeData', 'tapEdge', 'tapEdgeData', 'mouseoverNodeData', 'mouseoverEdgeData', 'selectedNodeData', 'selectedEdgeData', 'generateImage', 'imageData']
         self.available_wildcard_properties =            []
 
         _explicit_args = kwargs.pop('_explicit_args')