# Polus Render
`polus-render` makes Polus Render available as a Pypi package for Jupyter Lab.
Polus Render allows visualizing tiled raster datasets in Zarr and TIFF formats, as well as vector overlays in MicroJSON format. It uses lookup tables to map intensity values in these datasets to colors.
The are three ways to load the data:
1. Specifying a URL to a server serving the data.
2. Specifying a local path to a file from JupyterLab.
3. Dragging-and-dropping the dataset does not use a server.
Please note that [jupyterlab_polus_render](https://github.com/PolusAI/jupyterlab-extensions/tree/master/jupyterlab_polus_render) is the improved version of this package.
<img src="images/home.png"/>
# Requirements
* Python 3.9+
* [polus-server-ext](https://github.com/PolusAI/polus-prototypes/tree/master/polus-server-ext) iff running jupyter notebooks remotely.
# Installation
```
pip install "git+https://github.com/PolusAI/polus-prototypes.git#egg=polus-render&subdirectory=polus-render"
```
# Dev Installation
```
git clone https://github.com/PolusAI/polus-prototypes.git
cd polus-prototypes/polus-render/
[optional] python -m venv venv
[optional] "venv/Scripts/Activate"
pip install -r requirements.txt
```
Optional steps refer to setting up venv which is recommended.
# Project File Structure
```
polus-render
| Build Instructions.md // Instructions on how to update Pypi project
| MANIFEST.in // Packaging entries
| pyproject.toml // Pypi config
| README
| requirements.txt
└───polus
| polus_render.py // Main file, contains render function used by user
| render_server.py // Contains server only used for serving local build of Polus Render
├───apps
│ ├───render-ui // Static Polus Render files
│ └───updog-render // Server used for serving files.
```
# Build Instructions
- cd to `polus-render` root directory.
- `py -m build`
- `py -m twine upload dist/*`
- Enter `__token__` as user and reference API keys for password
# Adding a static build of Polus Render
- Remove all existing files in `~/polus-render/polus/apps/render-ui`.
- Run `npx nx build render-ui` in your Polus Render folder.
- Tranfer generated files from `/Polus Render/dist/apps/render-ui` into `/polus-render/polus/apps/render-ui`.
# Submodules
- [Updog-Render](https://github.com/jcaxle/updog-render/tree/71b6b938452f63412eea8edf29b9ff10f4c243dd)
# Static Render Features
| Version | Zarr from URL/Path | TIF from URL/Path | Micro-JSON Support | Zarr/TIF Drag & Drop | Micro-JSON Drag & Drop |
|----------------|---------------|---------------|----------------|-----------|-----|
| Local | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:
# Drag & Drop Demo
<img src="images/drag-drop.gif"/>
# Sample usage
``` Python
from polus.polus_render import render, nb_render
# pathlib and urllib are built-ins
from urllib.parse import urlparse
from pathlib import Path
# Embeds an IFrame of a static build of Polus Render into Jupyter Notebooks
render()
# Embeds an IFrame of Polus Render into Jupyter Notebooks
render(use_local_render=False)
# Embeds an IFrame of a static build of Polus Render with an image hosted locally at "C:\Users\JeffChen\OneDrive - Axle Informatics\Documents\zarr files\pyramid.zarr"
render(image_location=Path(r"C:\Users\JeffChen\OneDrive - Axle Informatics\Documents\zarr files\pyramid.zarr"))
# Embeds an IFrame of a static build of Polus Render with an image and overlay file that is hosted locally
render(image_location=Path(r"C:\Users\JeffChen\OneDrive - Axle Informatics\Documents\zarr files\pyramid.zarr"), \
microjson_overlay_location=Path(r"C:\Users\JeffChen\OneDrive - Axle Informatics\Documents\overlay files\x00_y01_c1_segmentations.json"))
# Embeds an IFrame of a static build of Polus Render with an image hosted remotely
render(image_location=urlparse("https://viv-demo.storage.googleapis.com/LuCa-7color_3x3component_data.ome.tif"))
# Embeds an IFrame with a height of 1080 of a local build of Polus Render.
render(height=1080)
# Embeds an IFrame into remote JupyterLab notebook. Use this function with argument nbhub_url to specify your notebooks url which must have lab in its url
nb_render(nbhub_url=urlparse("https://jh.scb-ncats.io/user/jeff.chen@axleinfo.com/user-namespaces/lab?"), image_location=Path("work/pyramid.zarr"))
```
# Functions
Use `render()` if you are running `polus-render` locally. Use `nb_render()` iff you are using remote JupyterLab whose root is `/home/jovyan/`
``` Python
def render(image_location:Union[ParseResult, PurePath] = "", microjson_overlay_location:Union[ParseResult, PurePath] = "", width:int=960, height:int=500, image_port:int=0, \
microjson_overlay_port:int=0, use_local_render:bool=True, render_url:str = "https://render.ci.ncats.io/")->str:
"""
Displays Polus Render with args to specify display dimensions, port to serve,
image files to use, and overlay to use.
Param:
image_location(ParseResult|Purepath): Acquired from urllib.parse.ParseResult or Path, renders url in render.
If not specified, renders default render url.
microjson_overlay_location(ParseResult|Purepath): Acquired from urllib.parse.ParseResult or Path, renders url in render.
If not specified, renders default render url
width (int): width of render to be displayed, default is 960
height (int): height of render to be displayed, default is 500
image_port (int): Port to run local image server if used (default is 0 which is the 1st available port).
microjson_overlay_port (int): Port to run local overlay server if used (default is 0 which is the 1st available port).
use_local_render (bool): True to run local build of render with 1st available port, False to use render_url (default is True)
render_url (str): URL which refers to Polus Render. Used when run_local_render is False. (default is https://render.ci.ncats.io/)
Pre: zarr_port and json_port selected (if used) is not in use IF path given is Purepath
Returns: Render URL
"""
def nb_render(nbhub_url:ParseResult,image_location:Union[ParseResult, PurePath] = "", microjson_overlay_location:Union[ParseResult, PurePath] = "", width:int=960, height:int=500, \
use_local_render:bool=True, render_url:str = "https://render.ci.ncats.io/")->str:
"""
Variant of render() used for remote jupyter notebooks. Read render() for usage information
Param:
nbhub_url: URL used used for jupyterhub. Contains '/lab/' in its uri
image_location(ParseResult|Purepath): Acquired from urllib.parse.ParseResult or Path, renders url in render.
If not specified, renders default render url.
microjson_overlay_location(ParseResult|Purepath): Acquired from urllib.parse.ParseResult or Path, renders url in render.
If not specified, renders default render url
width (int): width of render to be displayed, default is 960
height (int): height of render to be displayed, default is 500
run_local_render (bool): True to run local build of render with 1st available port, False to use render_url (default is True)
render_url (str): URL which refers to Polus Render. Used when run_local_render is False. (default is https://render.ci.ncats.io/)
Returns: Render URL
"""
```
# Implementation Details
- Render application is loaded in an IFrame.
- `render()` and `nb_render()` builds up URL scheme fragments for render url, image url, and microjson url. It then combines url fragments into a single url which is displayed through an embedded IFrame.
- Static build of Polus Render as well as files to be displayed in `nb_render()` are served by Jupyter Server extension.
- Dragging-and-dropping the dataset does not use a server. It calls an API from the front end (It should the this under the hood https://developer.mozilla.org/en-US/docs/Web/API/File_API).
# Misc Implementation Details
- Two type of servers are used.
>1. Python HTTPServer with CORS and OPTIONS functionality to serve Render.
>2. Modified UpDog Flask server to serve local files to Render.
# Acknowledgements
- UpDog: https://github.com/sc0tfree/updog
Raw data
{
"_id": null,
"home_page": "",
"name": "polus-render",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "Jeff Chen <Jeff.Chen@axleinfo.com>",
"download_url": "https://files.pythonhosted.org/packages/72/be/428bded6dda1004aabc1e6c2063edd371bae23a3dcf08d129b63c0199b0d/polus-render-0.1.0.tar.gz",
"platform": null,
"description": "# Polus Render\n\n`polus-render` makes Polus Render available as a Pypi package for Jupyter Lab.\n\nPolus Render allows visualizing tiled raster datasets in Zarr and TIFF formats, as well as vector overlays in MicroJSON format. It uses lookup tables to map intensity values in these datasets to colors.\n\nThe are three ways to load the data:\n\n1. Specifying a URL to a server serving the data.\n2. Specifying a local path to a file from JupyterLab.\n3. Dragging-and-dropping the dataset does not use a server.\n\nPlease note that [jupyterlab_polus_render](https://github.com/PolusAI/jupyterlab-extensions/tree/master/jupyterlab_polus_render) is the improved version of this package.\n\n<img src=\"images/home.png\"/>\n\n# Requirements\n* Python 3.9+\n* [polus-server-ext](https://github.com/PolusAI/polus-prototypes/tree/master/polus-server-ext) iff running jupyter notebooks remotely.\n\n# Installation\n```\npip install \"git+https://github.com/PolusAI/polus-prototypes.git#egg=polus-render&subdirectory=polus-render\"\n```\n\n# Dev Installation\n```\ngit clone https://github.com/PolusAI/polus-prototypes.git\ncd polus-prototypes/polus-render/\n[optional] python -m venv venv\n[optional] \"venv/Scripts/Activate\"\npip install -r requirements.txt\n```\nOptional steps refer to setting up venv which is recommended.\n\n# Project File Structure\n```\npolus-render\n| Build Instructions.md // Instructions on how to update Pypi project\n| MANIFEST.in // Packaging entries\n| pyproject.toml // Pypi config \n| README \n| requirements.txt\n\u2514\u2500\u2500\u2500polus\n | polus_render.py // Main file, contains render function used by user\n | render_server.py // Contains server only used for serving local build of Polus Render\n \u251c\u2500\u2500\u2500apps \n \u2502 \u251c\u2500\u2500\u2500render-ui // Static Polus Render files\n \u2502 \u2514\u2500\u2500\u2500updog-render // Server used for serving files.\n```\n\n# Build Instructions\n- cd to `polus-render` root directory.\n- `py -m build`\n- `py -m twine upload dist/*`\n- Enter `__token__` as user and reference API keys for password\n\n# Adding a static build of Polus Render\n- Remove all existing files in `~/polus-render/polus/apps/render-ui`. \n- Run `npx nx build render-ui` in your Polus Render folder.\n- Tranfer generated files from `/Polus Render/dist/apps/render-ui` into `/polus-render/polus/apps/render-ui`. \n\n# Submodules\n- [Updog-Render](https://github.com/jcaxle/updog-render/tree/71b6b938452f63412eea8edf29b9ff10f4c243dd)\n\n# Static Render Features\n| Version | Zarr from URL/Path | TIF from URL/Path | Micro-JSON Support | Zarr/TIF Drag & Drop | Micro-JSON Drag & Drop | \n|----------------|---------------|---------------|----------------|-----------|-----|\n| Local | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:\n\n# Drag & Drop Demo\n<img src=\"images/drag-drop.gif\"/>\n\n# Sample usage\n``` Python\nfrom polus.polus_render import render, nb_render\n\n# pathlib and urllib are built-ins\nfrom urllib.parse import urlparse\nfrom pathlib import Path\n\n# Embeds an IFrame of a static build of Polus Render into Jupyter Notebooks\nrender()\n\n# Embeds an IFrame of Polus Render into Jupyter Notebooks\nrender(use_local_render=False)\n\n# Embeds an IFrame of a static build of Polus Render with an image hosted locally at \"C:\\Users\\JeffChen\\OneDrive - Axle Informatics\\Documents\\zarr files\\pyramid.zarr\"\nrender(image_location=Path(r\"C:\\Users\\JeffChen\\OneDrive - Axle Informatics\\Documents\\zarr files\\pyramid.zarr\"))\n\n# Embeds an IFrame of a static build of Polus Render with an image and overlay file that is hosted locally\nrender(image_location=Path(r\"C:\\Users\\JeffChen\\OneDrive - Axle Informatics\\Documents\\zarr files\\pyramid.zarr\"), \\\nmicrojson_overlay_location=Path(r\"C:\\Users\\JeffChen\\OneDrive - Axle Informatics\\Documents\\overlay files\\x00_y01_c1_segmentations.json\"))\n\n# Embeds an IFrame of a static build of Polus Render with an image hosted remotely\nrender(image_location=urlparse(\"https://viv-demo.storage.googleapis.com/LuCa-7color_3x3component_data.ome.tif\"))\n\n# Embeds an IFrame with a height of 1080 of a local build of Polus Render.\nrender(height=1080)\n\n# Embeds an IFrame into remote JupyterLab notebook. Use this function with argument nbhub_url to specify your notebooks url which must have lab in its url\nnb_render(nbhub_url=urlparse(\"https://jh.scb-ncats.io/user/jeff.chen@axleinfo.com/user-namespaces/lab?\"), image_location=Path(\"work/pyramid.zarr\"))\n```\n\n# Functions\nUse `render()` if you are running `polus-render` locally. Use `nb_render()` iff you are using remote JupyterLab whose root is `/home/jovyan/`\n``` Python\ndef render(image_location:Union[ParseResult, PurePath] = \"\", microjson_overlay_location:Union[ParseResult, PurePath] = \"\", width:int=960, height:int=500, image_port:int=0, \\\n microjson_overlay_port:int=0, use_local_render:bool=True, render_url:str = \"https://render.ci.ncats.io/\")->str:\n \"\"\"\n Displays Polus Render with args to specify display dimensions, port to serve,\n image files to use, and overlay to use.\n \n Param:\n image_location(ParseResult|Purepath): Acquired from urllib.parse.ParseResult or Path, renders url in render.\n If not specified, renders default render url.\n microjson_overlay_location(ParseResult|Purepath): Acquired from urllib.parse.ParseResult or Path, renders url in render.\n If not specified, renders default render url\n width (int): width of render to be displayed, default is 960\n height (int): height of render to be displayed, default is 500\n image_port (int): Port to run local image server if used (default is 0 which is the 1st available port).\n microjson_overlay_port (int): Port to run local overlay server if used (default is 0 which is the 1st available port).\n use_local_render (bool): True to run local build of render with 1st available port, False to use render_url (default is True)\n render_url (str): URL which refers to Polus Render. Used when run_local_render is False. (default is https://render.ci.ncats.io/)\n Pre: zarr_port and json_port selected (if used) is not in use IF path given is Purepath\n Returns: Render URL\n \"\"\"\n\ndef nb_render(nbhub_url:ParseResult,image_location:Union[ParseResult, PurePath] = \"\", microjson_overlay_location:Union[ParseResult, PurePath] = \"\", width:int=960, height:int=500, \\\n use_local_render:bool=True, render_url:str = \"https://render.ci.ncats.io/\")->str:\n \"\"\"\n Variant of render() used for remote jupyter notebooks. Read render() for usage information\n\n Param:\n nbhub_url: URL used used for jupyterhub. Contains '/lab/' in its uri\n image_location(ParseResult|Purepath): Acquired from urllib.parse.ParseResult or Path, renders url in render.\n If not specified, renders default render url.\n microjson_overlay_location(ParseResult|Purepath): Acquired from urllib.parse.ParseResult or Path, renders url in render.\n If not specified, renders default render url\n width (int): width of render to be displayed, default is 960\n height (int): height of render to be displayed, default is 500\n run_local_render (bool): True to run local build of render with 1st available port, False to use render_url (default is True)\n render_url (str): URL which refers to Polus Render. Used when run_local_render is False. (default is https://render.ci.ncats.io/)\n Returns: Render URL\n \"\"\"\n```\n\n# Implementation Details\n- Render application is loaded in an IFrame.\n- `render()` and `nb_render()` builds up URL scheme fragments for render url, image url, and microjson url. It then combines url fragments into a single url which is displayed through an embedded IFrame.\n- Static build of Polus Render as well as files to be displayed in `nb_render()` are served by Jupyter Server extension.\n- Dragging-and-dropping the dataset does not use a server. It calls an API from the front end (It should the this under the hood https://developer.mozilla.org/en-US/docs/Web/API/File_API).\n\n# Misc Implementation Details\n- Two type of servers are used.\n>1. Python HTTPServer with CORS and OPTIONS functionality to serve Render.\n>2. Modified UpDog Flask server to serve local files to Render.\n\n# Acknowledgements\n- UpDog: https://github.com/sc0tfree/updog\n",
"bugtrack_url": null,
"license": "",
"summary": "Displays Polus Render dashboard in JupyterLabs.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/jcaxle/polus-render"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "51f31fe73b1e0932182a9f7162e6c368e011a42bd9c6f9e792a24f0d793f89b0",
"md5": "f4dc8ed43f03c5d8c8f0ebe80bb4f0ff",
"sha256": "a23000be7eca112da793831772b1ed71c133d8557d91eeb66c97b57b71d74aa5"
},
"downloads": -1,
"filename": "polus_render-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f4dc8ed43f03c5d8c8f0ebe80bb4f0ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 4954428,
"upload_time": "2023-12-07T16:02:16",
"upload_time_iso_8601": "2023-12-07T16:02:16.359475Z",
"url": "https://files.pythonhosted.org/packages/51/f3/1fe73b1e0932182a9f7162e6c368e011a42bd9c6f9e792a24f0d793f89b0/polus_render-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "72be428bded6dda1004aabc1e6c2063edd371bae23a3dcf08d129b63c0199b0d",
"md5": "6040da481ab005297d7aabf415c48333",
"sha256": "8b3d9f87c98608949c4703bae55de6876d909738077ef2bf931a73305d6a5072"
},
"downloads": -1,
"filename": "polus-render-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6040da481ab005297d7aabf415c48333",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 8434838,
"upload_time": "2023-12-07T16:02:28",
"upload_time_iso_8601": "2023-12-07T16:02:28.128194Z",
"url": "https://files.pythonhosted.org/packages/72/be/428bded6dda1004aabc1e6c2063edd371bae23a3dcf08d129b63c0199b0d/polus-render-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-07 16:02:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jcaxle",
"github_project": "polus-render",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "colorama",
"specs": [
[
"==",
"0.4.6"
]
]
},
{
"name": "flask",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "Flask-HTTPAuth",
"specs": [
[
"==",
"4.8.0"
]
]
},
{
"name": "werkzeug",
"specs": [
[
"==",
"3.0.1"
]
]
},
{
"name": "pyopenssl",
"specs": [
[
"==",
"23.2.0"
]
]
},
{
"name": "flask_cors",
"specs": [
[
"==",
"3.0.10"
]
]
}
],
"lcname": "polus-render"
}
JSON
