# dash_slicer
A volume slicer for Dash
Create slice views along a given dimension, and allows multiple such
views to be linked, to help with navigation. Supports anisotropic data,
mask overlays, and more.
<img width='700' src='https://user-images.githubusercontent.com/3015475/102329845-28a67880-3f89-11eb-82de-2cc2ff463a53.png'></img>
## Status
This work is marked as alpha - some essential features are still in
development, and some parts of the API may change in future releases.
## Installation
```
$ pip install dash-slicer
```
Dash-slicer depends on Python 3.6+ plus some [dependencies](requirements.txt).
## Usage example
```py
import dash
from dash import html
from dash_slicer import VolumeSlicer
import imageio
app = dash.Dash(__name__, update_title=None)
vol = imageio.volread("imageio:stent.npz")
slicer = VolumeSlicer(app, vol)
app.layout = html.Div([slicer.graph, slicer.slider, *slicer.stores])
if __name__ == "__main__":
app.run_server(debug=True, dev_tools_props_check=False)
```
See [the guide](https://dash.plotly.com/slicer) for more examples and explanations.
A complete app that uses dash-slicer is [dash-vocid-xray](https://dash-gallery.plotly.host/dash-covid-xray/)
([source](https://github.com/plotly/dash-sample-apps/blob/master/apps/dash-covid-xray/app.py)).
## License
This code is distributed under the MIT license.
## Developers
* Make sure that you have Python with the appropriate dependencies installed, e.g. via `venv`.
* Run `pip install -e .` to do an in-place install of the package.
* Run the examples using e.g. `python examples/all_features.py`
* Use `black .` to autoformat.
* Use `flake8 .` to lint.
* Use `pytest .` to run the tests.
* Use `python update_docs_in_readme.py` to update the readme when needed.
On every PR, an app with the same name as your branch is deployed to the Dash
playground instance so that you can change whether your changes did not break
the package.
Release procedure:
* Bump version in `__init__.py` (and commit this change).
* Run `git tag v?.? && git push origin v?.?`
* On GH, turn that tag into a release and write release notes.
* Clear the dist dir.
* Run `python setup.py sdist bdist_wheel`
* Run `twine upload dist/*`
* Bump version of dash-slicer in dash-docs.
## Reference
<!--- The below is autogenerated - do not edit --->
### The VolumeSlicer class
**class `VolumeSlicer(app, volume, *, spacing=None, origin=None, axis=0, reverse_y=True, clim=None, scene_id=None, color=None, thumbnail=True)`**
A slicer object to show 3D image data in Dash. Upon
instantiation one can provide the following parameters:
* `app` (`dash.Dash`): the Dash application instance.
* `volume` (`ndarray`): the 3D numpy array to slice through. The dimensions
are assumed to be in zyx order. If this is not the case, you can
use `np.swapaxes` to make it so.
* `spacing` (tuple of `float`): the distance between voxels for each
dimension (zyx). The spacing and origin are applied to make the slice
drawn in "scene space" rather than "voxel space".
* `origin` (tuple of `float`): the offset for each dimension (zyx).
* `axis` (`int`): the dimension to slice in. Default 0.
* `reverse_y` (`bool`): whether to reverse the y-axis, so that the origin of
the slice is in the top-left, rather than bottom-left. Default True.
Note: setting this to False affects performance, see #12. This has been
fixed, but the fix has not yet been released with Dash.
* `clim` (tuple of `float`): the (initial) contrast limits. Default the min
and max of the volume.
* `scene_id` (`str`): the scene that this slicer is part of. Slicers
that have the same scene-id show each-other's positions with
line indicators. By default this is derived from `id(volume)`.
* `color` (`str`): the color for this slicer. By default the color
is a shade of blue, orange, or green, depending on the axis. Set
to empty string to prevent drawing indicators for this slicer.
* `thumbnail` (`int` or `bool`): the preferred size of low-resolution data
to be uploaded to the client. If `False`, the full-resolution data are
uploaded client-side. If `True` (default), a default value of 32 is used.
Note that this is not a Dash Component. The components that make
up the slicer (and which must be present in the layout) are:
`slicer.graph`, `slicer.slider`, and `slicer.stores`.
**method `VolumeSlicer.create_overlay_data(mask, color=None)`**
Given a 3D mask array, create an object that can be used as
output for `slicer.overlay_data`. Set mask to `None` to clear the mask.
The color can be a hex color or an rgb/rgba tuple. Alternatively,
color can be a list of such colors, defining a colormap.
**property `VolumeSlicer.axis`** (`int`): The axis to slice.
**property `VolumeSlicer.clim`**: A `dcc.Store` to be used as Output, representing the contrast
limits as a 2-element tuple. This value should probably not be
changed too often (e.g. on slider drag) because the thumbnail
data is recreated on each change.
**property `VolumeSlicer.extra_traces`**: A `dcc.Store` to be used as an Output to define additional
traces to be shown in this slicer. The data must be a list of
dictionaries, with each dict representing a raw trace object.
**property `VolumeSlicer.graph`**: The `dcc.Graph` for this slicer. Use `graph.figure` to access the
Plotly Figure object.
**property `VolumeSlicer.nslices`** (`int`): The number of slices for this slicer.
**property `VolumeSlicer.overlay_data`**: A `dcc.Store` to be used an Output for the overlay data. The
form of this data is considered an implementation detail; users
are expected to use `create_overlay_data` to create it.
**property `VolumeSlicer.scene_id`** (`str`): The id of the "virtual scene" for this slicer. Slicers that have
the same scene_id show each-other's positions.
**property `VolumeSlicer.slider`**: The `dcc.Slider` to change the index for this slicer. If you
don't want to use the slider, wrap it in a div with style
`display: none`.
**property `VolumeSlicer.state`**: A `dcc.Store` representing the current state of the slicer (present
in slicer.stores). This store is intended for use as State or Input.
Its data is a dict with the fields:
* "index": the integer slice index.
* "index_changed": a bool indicating whether the index changed since last time.
* "xrange": the view range (2 floats) in the x-dimension (2D).
* "yrange": the view range (2 floats) in the y-dimension (2D).
* "zpos": the float position aling the axis, in scene coordinates.
* "axis": the axis (int) for this slicer.
* "color": the color (str) for this slicer.
The id of the store is a dictionary so it can be used in a
pattern matching Input. Its field are: context, scene, name.
Where scene is the scene_id and name is "state".
**property `VolumeSlicer.stores`**: A list of `dcc.Store` objects that the slicer needs to work.
These must be added to the app layout. Note that public stores
like `state` and `extra_traces` are also present in this list.
### Reacting to slicer state
It is possible to get notified of updates to slicer position and
view ranges. To get this for all slicers with a specific scene_id, create
a [pattern matching input](https://dash.plotly.com/pattern-matching-callbacks)
like this:
```py
Input({"scene": scene_id, "context": ALL, "name": "state"})
```
See the `state` property for details.
### Setting slicer positions
To programatically set the position of the slicer, create a `dcc.Store` with
a dictionary-id that has the following fields:
* 'context': a unique name for this store.
* 'scene': the scene_id of the slicer objects to set the position for.
* 'name': 'setpos'
The value in the store must be an 3-element tuple (x, y, z) in scene coordinates.
To apply the position for one dimension only, use e.g `(None, None, x)`.
### Performance tips
There tends to be a lot of interaction in an application that contains
slicer objects. To realize a smooth user experience, performance matters.
Here are some tips to help with that:
* Most importantly, when running the server in debug mode, consider setting
`dev_tools_props_check=False`.
* Also consider creating the `Dash` application with `update_title=None`.
* Setting `reverse_y` to False negatively affects performance. This will be
fixed in a future version of Plotly/Dash.
* For a smooth experience, avoid triggering unnecessary figure updates.
* When adding a callback that uses the slicer position, use the (rate limited)
`state` store rather than the slider value.
Raw data
{
"_id": null,
"home_page": "https://github.com/plotly/dash-slicer",
"name": "dash-slicer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6.0",
"maintainer_email": null,
"keywords": null,
"author": "Plotly",
"author_email": "almar.klein@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e5/d3/f39746fe4d952fe33e1b0393e917fa399785f1789101c7d6809114eb9046/dash-slicer-0.3.1.tar.gz",
"platform": null,
"description": "\n\n# dash_slicer\n\nA volume slicer for Dash\n\nCreate slice views along a given dimension, and allows multiple such\nviews to be linked, to help with navigation. Supports anisotropic data,\nmask overlays, and more.\n\n<img width='700' src='https://user-images.githubusercontent.com/3015475/102329845-28a67880-3f89-11eb-82de-2cc2ff463a53.png'></img>\n\n\n## Status\n\nThis work is marked as alpha - some essential features are still in\ndevelopment, and some parts of the API may change in future releases.\n\n\n## Installation\n\n```\n$ pip install dash-slicer\n```\n\nDash-slicer depends on Python 3.6+ plus some [dependencies](requirements.txt).\n\n\n## Usage example\n\n```py\nimport dash\nfrom dash import html\nfrom dash_slicer import VolumeSlicer\nimport imageio\n\napp = dash.Dash(__name__, update_title=None)\n\nvol = imageio.volread(\"imageio:stent.npz\")\nslicer = VolumeSlicer(app, vol)\n\napp.layout = html.Div([slicer.graph, slicer.slider, *slicer.stores])\n\nif __name__ == \"__main__\":\n app.run_server(debug=True, dev_tools_props_check=False)\n```\n\nSee [the guide](https://dash.plotly.com/slicer) for more examples and explanations.\nA complete app that uses dash-slicer is [dash-vocid-xray](https://dash-gallery.plotly.host/dash-covid-xray/)\n([source](https://github.com/plotly/dash-sample-apps/blob/master/apps/dash-covid-xray/app.py)).\n\n\n\n## License\n\nThis code is distributed under the MIT license.\n\n\n## Developers\n\n\n* Make sure that you have Python with the appropriate dependencies installed, e.g. via `venv`.\n* Run `pip install -e .` to do an in-place install of the package.\n* Run the examples using e.g. `python examples/all_features.py`\n\n* Use `black .` to autoformat.\n* Use `flake8 .` to lint.\n* Use `pytest .` to run the tests.\n* Use `python update_docs_in_readme.py` to update the readme when needed.\n\nOn every PR, an app with the same name as your branch is deployed to the Dash\nplayground instance so that you can change whether your changes did not break\nthe package.\n\nRelease procedure:\n\n* Bump version in `__init__.py` (and commit this change).\n* Run `git tag v?.? && git push origin v?.?`\n* On GH, turn that tag into a release and write release notes.\n* Clear the dist dir.\n* Run `python setup.py sdist bdist_wheel`\n* Run `twine upload dist/*`\n* Bump version of dash-slicer in dash-docs.\n\n\n## Reference\n\n<!--- The below is autogenerated - do not edit --->\n\n### The VolumeSlicer class\n\n**class `VolumeSlicer(app, volume, *, spacing=None, origin=None, axis=0, reverse_y=True, clim=None, scene_id=None, color=None, thumbnail=True)`**\n\nA slicer object to show 3D image data in Dash. Upon\ninstantiation one can provide the following parameters:\n\n* `app` (`dash.Dash`): the Dash application instance.\n* `volume` (`ndarray`): the 3D numpy array to slice through. The dimensions\n are assumed to be in zyx order. If this is not the case, you can\n use `np.swapaxes` to make it so.\n* `spacing` (tuple of `float`): the distance between voxels for each\n dimension (zyx). The spacing and origin are applied to make the slice\n drawn in \"scene space\" rather than \"voxel space\".\n* `origin` (tuple of `float`): the offset for each dimension (zyx).\n* `axis` (`int`): the dimension to slice in. Default 0.\n* `reverse_y` (`bool`): whether to reverse the y-axis, so that the origin of\n the slice is in the top-left, rather than bottom-left. Default True.\n Note: setting this to False affects performance, see #12. This has been\n fixed, but the fix has not yet been released with Dash.\n* `clim` (tuple of `float`): the (initial) contrast limits. Default the min\n and max of the volume.\n* `scene_id` (`str`): the scene that this slicer is part of. Slicers\n that have the same scene-id show each-other's positions with\n line indicators. By default this is derived from `id(volume)`.\n* `color` (`str`): the color for this slicer. By default the color\n is a shade of blue, orange, or green, depending on the axis. Set\n to empty string to prevent drawing indicators for this slicer.\n* `thumbnail` (`int` or `bool`): the preferred size of low-resolution data\n to be uploaded to the client. If `False`, the full-resolution data are\n uploaded client-side. If `True` (default), a default value of 32 is used.\n\nNote that this is not a Dash Component. The components that make\nup the slicer (and which must be present in the layout) are:\n`slicer.graph`, `slicer.slider`, and `slicer.stores`.\n\n**method `VolumeSlicer.create_overlay_data(mask, color=None)`**\n\nGiven a 3D mask array, create an object that can be used as\noutput for `slicer.overlay_data`. Set mask to `None` to clear the mask.\nThe color can be a hex color or an rgb/rgba tuple. Alternatively,\ncolor can be a list of such colors, defining a colormap.\n\n**property `VolumeSlicer.axis`** (`int`): The axis to slice.\n\n**property `VolumeSlicer.clim`**: A `dcc.Store` to be used as Output, representing the contrast\nlimits as a 2-element tuple. This value should probably not be\nchanged too often (e.g. on slider drag) because the thumbnail\ndata is recreated on each change.\n\n**property `VolumeSlicer.extra_traces`**: A `dcc.Store` to be used as an Output to define additional\ntraces to be shown in this slicer. The data must be a list of\ndictionaries, with each dict representing a raw trace object.\n\n**property `VolumeSlicer.graph`**: The `dcc.Graph` for this slicer. Use `graph.figure` to access the\nPlotly Figure object.\n\n**property `VolumeSlicer.nslices`** (`int`): The number of slices for this slicer.\n\n**property `VolumeSlicer.overlay_data`**: A `dcc.Store` to be used an Output for the overlay data. The\nform of this data is considered an implementation detail; users\nare expected to use `create_overlay_data` to create it.\n\n**property `VolumeSlicer.scene_id`** (`str`): The id of the \"virtual scene\" for this slicer. Slicers that have\nthe same scene_id show each-other's positions.\n\n**property `VolumeSlicer.slider`**: The `dcc.Slider` to change the index for this slicer. If you\ndon't want to use the slider, wrap it in a div with style\n`display: none`.\n\n**property `VolumeSlicer.state`**: A `dcc.Store` representing the current state of the slicer (present\nin slicer.stores). This store is intended for use as State or Input.\nIts data is a dict with the fields:\n\n* \"index\": the integer slice index.\n* \"index_changed\": a bool indicating whether the index changed since last time.\n* \"xrange\": the view range (2 floats) in the x-dimension (2D).\n* \"yrange\": the view range (2 floats) in the y-dimension (2D).\n* \"zpos\": the float position aling the axis, in scene coordinates.\n* \"axis\": the axis (int) for this slicer.\n* \"color\": the color (str) for this slicer.\n\nThe id of the store is a dictionary so it can be used in a\npattern matching Input. Its field are: context, scene, name.\nWhere scene is the scene_id and name is \"state\".\n\n**property `VolumeSlicer.stores`**: A list of `dcc.Store` objects that the slicer needs to work.\nThese must be added to the app layout. Note that public stores\nlike `state` and `extra_traces` are also present in this list.\n\n\n\n### Reacting to slicer state\n\nIt is possible to get notified of updates to slicer position and\nview ranges. To get this for all slicers with a specific scene_id, create\na [pattern matching input](https://dash.plotly.com/pattern-matching-callbacks)\nlike this:\n```py\nInput({\"scene\": scene_id, \"context\": ALL, \"name\": \"state\"})\n```\n\nSee the `state` property for details.\n\n\n### Setting slicer positions\n\nTo programatically set the position of the slicer, create a `dcc.Store` with\na dictionary-id that has the following fields:\n\n* 'context': a unique name for this store.\n* 'scene': the scene_id of the slicer objects to set the position for.\n* 'name': 'setpos'\n\nThe value in the store must be an 3-element tuple (x, y, z) in scene coordinates.\nTo apply the position for one dimension only, use e.g `(None, None, x)`.\n\n\n### Performance tips\n\nThere tends to be a lot of interaction in an application that contains\nslicer objects. To realize a smooth user experience, performance matters.\nHere are some tips to help with that:\n\n* Most importantly, when running the server in debug mode, consider setting\n `dev_tools_props_check=False`.\n* Also consider creating the `Dash` application with `update_title=None`.\n* Setting `reverse_y` to False negatively affects performance. This will be\n fixed in a future version of Plotly/Dash.\n* For a smooth experience, avoid triggering unnecessary figure updates.\n* When adding a callback that uses the slicer position, use the (rate limited)\n `state` store rather than the slider value.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A volume slicer for Dash",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/plotly/dash-slicer"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "200156d2874efd9897eb48c2bd7a684fe42432ae2ae14bc99d9247cf3d9a8f68",
"md5": "70ed6bb4560ea9ab823cc553b15ef18f",
"sha256": "68c821c017533f1014c984c93ad5c01ce306cdc633c3c7630fa1a2a8301d3d53"
},
"downloads": -1,
"filename": "dash_slicer-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "70ed6bb4560ea9ab823cc553b15ef18f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6.0",
"size": 19792,
"upload_time": "2024-03-29T08:53:07",
"upload_time_iso_8601": "2024-03-29T08:53:07.264477Z",
"url": "https://files.pythonhosted.org/packages/20/01/56d2874efd9897eb48c2bd7a684fe42432ae2ae14bc99d9247cf3d9a8f68/dash_slicer-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e5d3f39746fe4d952fe33e1b0393e917fa399785f1789101c7d6809114eb9046",
"md5": "b28e4cfca0743ee01d253042069e89b8",
"sha256": "95ec6237c3a19d008ff6878d09d5bb7dedb303c9d4aabc3f80bc073d2aa40f9c"
},
"downloads": -1,
"filename": "dash-slicer-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "b28e4cfca0743ee01d253042069e89b8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.0",
"size": 19954,
"upload_time": "2024-03-29T08:53:08",
"upload_time_iso_8601": "2024-03-29T08:53:08.991034Z",
"url": "https://files.pythonhosted.org/packages/e5/d3/f39746fe4d952fe33e1b0393e917fa399785f1789101c7d6809114eb9046/dash-slicer-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-29 08:53:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "plotly",
"github_project": "dash-slicer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"circle": true,
"requirements": [],
"lcname": "dash-slicer"
}
JSON
