examples/point-cloud-parameters.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0998f3eb-1c73-4e34-b406-007e1d795625",
   "metadata": {},
   "source": [
    "# Point cloud visualization parameters\n",
    "\n",
    "This notebook gives an overview of the various parameters that are available to change the appearance of the point cloud visualization and how to navigate through the points with the keyboard and mouse. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0467dca5-2eb0-4dcd-9859-3df15050842c",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from pybabylonjs import Show as show"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4a27ab65-9b45-47ba-9d10-0990da8de86a",
   "metadata": {},
   "source": [
    "Create a random point cloud to visualize and explore the parameters with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "419814fe-aabc-46e5-9865-dfdf7e63c05a",
   "metadata": {},
   "outputs": [],
   "source": [
    "(minx, maxx), (miny, maxy), (minz, maxz) = ((-80, 80), (-150, 150), (-5, 5))\n",
    "extent = 50.\n",
    "num_vals = 1000\n",
    "\n",
    "xs = np.random.default_rng().uniform(minx - extent, maxx + extent, num_vals)\n",
    "ys = np.random.default_rng().uniform(miny - extent, maxy + extent, num_vals)\n",
    "zs = np.random.default_rng().uniform(minx, maxz, num_vals)\n",
    "\n",
    "data = {\n",
    "   \"X\": xs,\n",
    "   \"Y\": ys,\n",
    "   \"Z\": zs,\n",
    "   \"Red\": np.random.default_rng().uniform(0., 1., num_vals),\n",
    "   \"Green\": np.random.default_rng().uniform(0., 1., num_vals),\n",
    "   \"Blue\": np.random.default_rng().uniform(0., 1., num_vals)\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "202e301e-4be1-417d-9a77-2ae0717a6d44",
   "metadata": {},
   "source": [
    "The below displays a default point cloud visualization with [BabylonJS](https://www.babylonjs.com/), where the points from `data` are used to create a [PointCloudSystem](https://doc.babylonjs.com/features/featuresDeepDive/particles/point_cloud_system). Click the menu in the top right corner to change the background color, and click the menu again to collapse the options. \n",
    "\n",
    "`source=\"dict\"` specifies that the data will be loaded from the `data` dictionary (`dict`) created above. This dictionary always needs to contain values for the location `X`, `Y` and `Z` and the RGB color for each point `Red`, `Green` and `Blue`, in this case scaled between 0 and 1. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a024e5d3-4198-4ba0-8c81-22ad0112f72e",
   "metadata": {},
   "outputs": [],
   "source": [
    "show.point_cloud(source=\"dict\",\n",
    "                 data=data,\n",
    "                 point_size = 10)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f577ef0e-e3c4-430d-ac06-4b12c644a2cf",
   "metadata": {},
   "source": [
    "The size of the points of defined by the `point_size`parameter. Other parameters that can be used to improve the looks of the visualization are:\n",
    "\n",
    "* `width` and `height` are the width and height of the display window in pixels\n",
    "* `color_scheme` is the initial background color: `dark` (default), `light` or ` blue`\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,6]` is then twice a far away from the centre in the X and Y direction, and 6 times as far away in the Z direction\n",
    "* `camera_location` is the location of the camera 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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "022751de-f2c2-4e59-a12f-a33a3badbe37",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "show.point_cloud(source=\"dict\",\n",
    "                 data=data,\n",
    "                 point_size = 20,\n",
    "                 width=1000,\n",
    "                 height=600,\n",
    "                 color_scheme=\"dark\",\n",
    "                 camera_zoom=[2,2,6],\n",
    "                 camera_location=2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "e590860a-47d2-411f-ba4e-7605a5440cb1",
   "metadata": {},
   "source": [
    "The size of the points can be interactively updated with the `point_type` parameter. Choose one of the below:\n",
    "\n",
    "* `fixed_screen_size` (default): each point has a constant size in pixels regardless of its distance to the camera\n",
    "* `fixed_world_size`: 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_size`: the same as `fixed_world_size` 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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0c41559c-9243-41c4-98db-024f3b3cb382",
   "metadata": {},
   "outputs": [],
   "source": [
    "show.point_cloud(source=\"dict\",\n",
    "                 data=data,\n",
    "                 point_size = 20,\n",
    "                 width=1000,\n",
    "                 height=600,\n",
    "                 color_scheme=\"dark\",\n",
    "                 camera_zoom=[2,2,6],\n",
    "                 camera_location=2,\n",
    "                 point_type = 'fixed_world_size')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "401bb0f4-1562-478d-a956-db67218b16af",
   "metadata": {},
   "source": [
    "It is possible to show each point as a 3D block instead of a 2D square, but note that this is more memory intensive and might slow down the visualization for large point clouds. To see a clearer distinction between the blocks [Eye Dome Lighting (EDL)](https://www.kitware.com/eye-dome-lighting-a-non-photorealistic-shading-technique/) can be added. \n",
    "\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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "28f6c561-f1bd-4409-a6d1-f5c3723dd50e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "show.point_cloud(source=\"dict\",\n",
    "                 data=data,\n",
    "                 point_size = 10,\n",
    "                 width=1000,\n",
    "                 height=600,\n",
    "                 camera_location=3,\n",
    "                 camera_zoom=[4,4,6],\n",
    "                 color_scheme=\"light\",\n",
    "                 use_sps=True,\n",
    "                 use_shader=True,\n",
    "                 edl_strength=5)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b7846c5f-a71b-40a1-94a8-f6e5c3edefca",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Navigating the point cloud\n",
    "\n",
    "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\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",
    "\n",
    "The below example shows some of these options where they are all set to move very fast:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "841bdccf-34c2-476f-a2d6-0e41823b9777",
   "metadata": {},
   "outputs": [],
   "source": [
    "show.point_cloud(source=\"dict\",\n",
    "                 data=data,\n",
    "                 point_size = 10,\n",
    "                 width=1000,\n",
    "                 height=600,\n",
    "                 camera_location=6,\n",
    "                 camera_zoom=[4,4,6],\n",
    "                 color_scheme=\"light\",\n",
    "                 wheel_precision=0.01,\n",
    "                 camera_up=20,\n",
    "                 move_speed=10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f28cd846-a920-4e5f-8b18-e57d70005452",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}