# TileDB-PyBabylonJS
[](https://codecov.io/gh/TileDB-Inc/PyBabylonJS)
[](https://dev.azure.com/TileDB-Inc/CI/_build/latest?definitionId=37&branchName=main)
The TileDB-PyBabylonJS library is a geospatial data visualization Python library that interactively visualizes TileDB arrays with [Babylon.js](https://www.babylonjs.com) in a Jupyter notebook widget.
The package is under development and currently contains point cloud visualizations with the option to stream all data from a TileDB array or define a bounding box to load a slice of the array
## Installation
This project is available from [PyPI](https://pypi.org/project/pybabylonjs/) and can be installed with `pip`:
```bash
pip install pybabylonjs
```
If you are using Jupyter Notebook 5.2 or earlier, you may also need to enable the nbextension:
```bash
jupyter nbextension enable --py [--sys-prefix|--user|--system] pybabylonjs
```
## Development Installation
Create and activate a development environment:
```bash
conda create -n pybabylonjs-dev -c conda-forge nodejs yarn python tree scipy 'pyarrow>2' numpy pandas tiledb-py jupyter-packaging jupyterlab
conda activate pybabylonjs-dev
pip install opencv-python
```
Fork or clone the repo and go to the main directory. Install the TileDB-PyBabylonJS Python package that will also build the TypeScript package:
```bash
pip install -e ".[test, examples]"
```
When developing extensions you need to manually enable the extensions with the notebook / lab frontend. For jupyter lab this is done by the command:
```bash
jupyter labextension install @jupyter-widgets/jupyterlab-manager
yarn run build
jupyter labextension develop . --overwrite
```
For a classic notebook you need to run:
```bash
jupyter nbextension install --sys-prefix --symlink --overwrite --py pybabylonjs
jupyter nbextension enable --sys-prefix --py pybabylonjs
```
Note that the `--symlink` flag doesn't work on Windows, so you will here have to run
the `install` command every time that you rebuild your extension. For certain installations
you might also need another flag instead of `--sys-prefix`.
### How to see your changes
#### TypeScript
The TypeScript code for the visualizations can be found in the [TileDB-Viz](https://github.com/TileDB-Inc/TileDB-Viz) repository. After making changes in TileDB-Viz build the package with:
`yarn build`
To then see these changes in TileDB-PyBabylonJS run:
`yarn add file:/path/to/TileDB-Viz/packages/core`
`yarn build`
And restart the notebook kernel.
#### Python
When you make a change to the Python code rebuild the package and restart the notebook kernel to see your changes.
## Usage
Jupyter notebooks are provided in the [examples folder](https://github.com/TileDB-Inc/TileDB-PyBabylonJS/tree/main/examples) for the following visualizations:
* [Point cloud visualization parameters](examples/point-cloud-parameters.ipynb) contains a description of all parameters
* [Slice of the Autzen point cloud](examples/autzen-slice.ipynb)
* [Slice of the Boulder point cloud](examples/boulder-slice.ipynb)
* [Streaming the Autzen point cloud](examples/autzen-streaming.ipynb)
* [Streaming the Bristol point cloud](examples/bristol-streaming.ipynb)
* [Streaming the Santorini point cloud](examples/santorini-streaming.ipynb)
[Sign up for a TileDB account](https://cloud.tiledb.com/auth/signup) and display a point cloud visualization from a TileDB cloud sparse array by specifying the bounding box of a slice of data:
```python
from pybabylonjs import Show as show
bbox = {
'X': [636800, 637200],
'Y': [852800, 853100],
'Z': [406.14, 615.26]
}
lidar_array = "autzen-classified"
show.point_cloud(source="cloud",
uri = "tiledb://TileDB-Inc/autzen_classified_tiledb",
token=token,
bbox = bbox,
point_size = 3,
rgb_max = 65535,
camera_up = 25,
camera_location = 2,
camera_zoom = [2,2,2],
point_type = 'fixed_screen_size',
width=1000,
height=600)
```
Or stream all data from a group of arrays:
```python
show.point_cloud(streaming=True,
uri="tiledb://TileDB-Inc/bristol",
token=token,
point_size = 4,
wheel_precision = 0.2,
color_scheme = 'dark',
width = 1200,
height = 800,
rgb_max = 255,
point_budget = 3500000,
camera_location = 8,
camera_zoom = [1, 1, 2],
camera_up = 50,
move_speed = 8,
point_type = 'fixed_world_size')
```
### Parameters
The following parameters can be set for a point cloud visualization:
* `camera_location` is the location of the arcRotateCamera in relation to the centre of the point cloud. 1: south, 2: south-east, 3: east, 4: north-east, 5: north, 6: north-west, 7: west, 8: south-west and 9: looking down from above the centre of the point cloud
* `camera_up` is the height of the initial location of the freeCamera
* `camera_zoom` scales the camera position relative to the centre of the point cloud with `[1,1,1]` being in the default position and `[2,2,2]` is then twice a far away from the centre in the X, Y and Z direction
* `color_scheme` is the initial background color: `dark` (default), `light` or ` blue`
* `data` is the dictionary with the point cloud data when `source = dict`. This dictionary needs to contain values for the location `X`, `Y` and `Z` and the RGB color for each point `Red`, `Green` and `Blue`
* `height` is the height of the display window in pixels
* `point_size` is the size of the points
* `point_type` is the interactive point size type
* `fixed_screen_size` (default): each point has a constant size in pixels regardless of its distance to the camera
* `fixed_world_space`: each point has a constant size in world space. This value should be set accordingly to the spacing of the points in world space
* `adaptive_world_space`: the same as `fixed_world_space` for the below example. But when streaming point cloud data, the point size depends on the locally loaded LODs at each point. The point density across all blocks of the same LOD should be the same and the point density should double at each LOD
* `source` is the data source (`cloud` (default), `local` or `dict`)
* `use_sps=True` displays the points as 3D blocks using a [Solid Particle System](https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/sps_intro)
* `use_shader=True` adds the EDL shading
* `edl_strength` is the strenght of the shader
* `wheel_precision` gives control over how fast to zoom with the mouse wheel
* `width` is the width of the display window in pixels
### Navigating the point cloud
There are two different cameras available to navigate the point cloud, the arcRotateCamera and freeCamera. Toggle between them with `c`. The initial camera is always the arcRotateCamera
**arcRotateCamera**
* Zoom in and out with the scroll wheel
* Rotate by dragging the mouse with left button down
* The parameter `wheel_precision` gives control over how fast to zoom with the mouse wheel
* The camera location and distance from the centre of the points can be changed with `camera_location` and `camera_zoom`
* Rotate through the `camera_locations` with `v`
* Change the background color between dark and light with `b`
**freeCamera**
* Move forward: `w` or `up`
* Move backward: `s` or `down`
* Move up: `e`
* Move down: `q`
* Move to the left: `a` or `left`
* Move to the right: `d` or `right`
* Rotate by dragging the mouse with left button down
* The initial camera position is the centre of the point cloud, the height of the location can be changed with the parameter `camera_up`
* The camera speed can be changed with the parameter `move_speed`
* Change the background color between dark and light with `b`
Raw data
{
"_id": null,
"home_page": "https://github.com/TileDB-Inc/TileDB-PyBabylonJS",
"name": "pybabylonjs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "Jupyter,JupyterLab,JupyterLab3",
"author": "TileDB",
"author_email": "support@tiledb.com",
"download_url": "",
"platform": "Linux",
"description": "\n# TileDB-PyBabylonJS\n\n[](https://codecov.io/gh/TileDB-Inc/PyBabylonJS)\n[](https://dev.azure.com/TileDB-Inc/CI/_build/latest?definitionId=37&branchName=main)\n\n\nThe TileDB-PyBabylonJS library is a geospatial data visualization Python library that interactively visualizes TileDB arrays with [Babylon.js](https://www.babylonjs.com) in a Jupyter notebook widget.\n\nThe package is under development and currently contains point cloud visualizations with the option to stream all data from a TileDB array or define a bounding box to load a slice of the array\n\n## Installation\n\nThis project is available from [PyPI](https://pypi.org/project/pybabylonjs/) and can be installed with `pip`:\n\n```bash\npip install pybabylonjs\n```\n\nIf you are using Jupyter Notebook 5.2 or earlier, you may also need to enable the nbextension:\n```bash\njupyter nbextension enable --py [--sys-prefix|--user|--system] pybabylonjs\n```\n\n## Development Installation\n\nCreate and activate a development environment:\n\n```bash\nconda create -n pybabylonjs-dev -c conda-forge nodejs yarn python tree scipy 'pyarrow>2' numpy pandas tiledb-py jupyter-packaging jupyterlab\n\nconda activate pybabylonjs-dev\n\npip install opencv-python\n```\n\nFork or clone the repo and go to the main directory. Install the TileDB-PyBabylonJS Python package that will also build the TypeScript package:\n\n```bash\npip install -e \".[test, examples]\"\n```\n\nWhen developing extensions you need to manually enable the extensions with the notebook / lab frontend. For jupyter lab this is done by the command:\n\n```bash\njupyter labextension install @jupyter-widgets/jupyterlab-manager\nyarn run build\njupyter labextension develop . --overwrite\n```\n\nFor a classic notebook you need to run:\n\n```bash\njupyter nbextension install --sys-prefix --symlink --overwrite --py pybabylonjs\njupyter nbextension enable --sys-prefix --py pybabylonjs\n```\n\nNote that the `--symlink` flag doesn't work on Windows, so you will here have to run\nthe `install` command every time that you rebuild your extension. For certain installations\nyou might also need another flag instead of `--sys-prefix`.\n\n### How to see your changes\n\n#### TypeScript\n\nThe TypeScript code for the visualizations can be found in the [TileDB-Viz](https://github.com/TileDB-Inc/TileDB-Viz) repository. After making changes in TileDB-Viz build the package with:\n\n`yarn build`\n\nTo then see these changes in TileDB-PyBabylonJS run:\n\n`yarn add file:/path/to/TileDB-Viz/packages/core`\n\n`yarn build`\n\nAnd restart the notebook kernel. \n\n#### Python\n\nWhen you make a change to the Python code rebuild the package and restart the notebook kernel to see your changes.\n\n## Usage\n\nJupyter notebooks are provided in the [examples folder](https://github.com/TileDB-Inc/TileDB-PyBabylonJS/tree/main/examples) for the following visualizations:\n\n* [Point cloud visualization parameters](examples/point-cloud-parameters.ipynb) contains a description of all parameters\n* [Slice of the Autzen point cloud](examples/autzen-slice.ipynb)\n* [Slice of the Boulder point cloud](examples/boulder-slice.ipynb)\n* [Streaming the Autzen point cloud](examples/autzen-streaming.ipynb)\n* [Streaming the Bristol point cloud](examples/bristol-streaming.ipynb)\n* [Streaming the Santorini point cloud](examples/santorini-streaming.ipynb) \n\n[Sign up for a TileDB account](https://cloud.tiledb.com/auth/signup) and display a point cloud visualization from a TileDB cloud sparse array by specifying the bounding box of a slice of data:\n\n```python\nfrom pybabylonjs import Show as show\n\nbbox = {\n 'X': [636800, 637200],\n 'Y': [852800, 853100],\n 'Z': [406.14, 615.26]\n}\n\nlidar_array = \"autzen-classified\"\n\nshow.point_cloud(source=\"cloud\",\n uri = \"tiledb://TileDB-Inc/autzen_classified_tiledb\",\n token=token,\n bbox = bbox,\n point_size = 3,\n rgb_max = 65535,\n camera_up = 25,\n camera_location = 2,\n camera_zoom = [2,2,2],\n point_type = 'fixed_screen_size',\n width=1000,\n height=600)\n```\n\nOr stream all data from a group of arrays: \n\n```python\nshow.point_cloud(streaming=True,\n uri=\"tiledb://TileDB-Inc/bristol\",\n token=token, \n point_size = 4,\n wheel_precision = 0.2,\n color_scheme = 'dark',\n width = 1200,\n height = 800, \n rgb_max = 255,\n point_budget = 3500000,\n camera_location = 8,\n camera_zoom = [1, 1, 2],\n camera_up = 50, \n move_speed = 8,\n point_type = 'fixed_world_size')\n```\n\n### Parameters\n\nThe following parameters can be set for a point cloud visualization:\n\n* `camera_location` is the location of the arcRotateCamera in relation to the centre of the point cloud. 1: south, 2: south-east, 3: east, 4: north-east, 5: north, 6: north-west, 7: west, 8: south-west and 9: looking down from above the centre of the point cloud\n* `camera_up` is the height of the initial location of the freeCamera\n* `camera_zoom` scales the camera position relative to the centre of the point cloud with `[1,1,1]` being in the default position and `[2,2,2]` is then twice a far away from the centre in the X, Y and Z direction\n* `color_scheme` is the initial background color: `dark` (default), `light` or ` blue`\n* `data` is the dictionary with the point cloud data when `source = dict`. This dictionary needs to contain values for the location `X`, `Y` and `Z` and the RGB color for each point `Red`, `Green` and `Blue`\n* `height` is the height of the display window in pixels\n* `point_size` is the size of the points\n* `point_type` is the interactive point size type\n * `fixed_screen_size` (default): each point has a constant size in pixels regardless of its distance to the camera\n * `fixed_world_space`: each point has a constant size in world space. This value should be set accordingly to the spacing of the points in world space\n * `adaptive_world_space`: the same as `fixed_world_space` for the below example. But when streaming point cloud data, the point size depends on the locally loaded LODs at each point. The point density across all blocks of the same LOD should be the same and the point density should double at each LOD\n* `source` is the data source (`cloud` (default), `local` or `dict`)\n* `use_sps=True` displays the points as 3D blocks using a [Solid Particle System](https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/sps_intro)\n* `use_shader=True` adds the EDL shading \n* `edl_strength` is the strenght of the shader\n* `wheel_precision` gives control over how fast to zoom with the mouse wheel\n* `width` is the width of the display window in pixels\n\n### Navigating the point cloud\n\nThere are two different cameras available to navigate the point cloud, the arcRotateCamera and freeCamera. Toggle between them with `c`. The initial camera is always the arcRotateCamera\n\n**arcRotateCamera** \n* Zoom in and out with the scroll wheel\n* Rotate by dragging the mouse with left button down\n* The parameter `wheel_precision` gives control over how fast to zoom with the mouse wheel\n* The camera location and distance from the centre of the points can be changed with `camera_location` and `camera_zoom`\n* Rotate through the `camera_locations` with `v`\n* Change the background color between dark and light with `b`\n\n**freeCamera**\n* Move forward: `w` or `up`\n* Move backward: `s` or `down`\n* Move up: `e`\n* Move down: `q`\n* Move to the left: `a` or `left`\n* Move to the right: `d` or `right`\n* Rotate by dragging the mouse with left button down\n* The initial camera position is the centre of the point cloud, the height of the location can be changed with the parameter `camera_up`\n* The camera speed can be changed with the parameter `move_speed`\n* Change the background color between dark and light with `b`\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "BabylonJS widget",
"version": "1.5.2",
"project_urls": {
"Homepage": "https://github.com/TileDB-Inc/TileDB-PyBabylonJS"
},
"split_keywords": [
"jupyter",
"jupyterlab",
"jupyterlab3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c95a5d54bc2d4be3ea5f20b403fb92ba3a07aeb0ed828bf23785dcbe0d2d18c9",
"md5": "de3cb5f14a0db37437cb0882cb2dd8a3",
"sha256": "1ce964db47a859f8bef411954dac2b88f13b609d13ec50de7eddf333a05f57bd"
},
"downloads": -1,
"filename": "pybabylonjs-1.5.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "de3cb5f14a0db37437cb0882cb2dd8a3",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 9709392,
"upload_time": "2024-01-30T15:29:41",
"upload_time_iso_8601": "2024-01-30T15:29:41.065381Z",
"url": "https://files.pythonhosted.org/packages/c9/5a/5d54bc2d4be3ea5f20b403fb92ba3a07aeb0ed828bf23785dcbe0d2d18c9/pybabylonjs-1.5.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-30 15:29:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TileDB-Inc",
"github_project": "TileDB-PyBabylonJS",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pybabylonjs"
}
JSON
