Web visualizer initial commit

.gitignore

@@ -0,0 +1,26 @@
+.DS_Store
+node_modules
+.venv
+
+# local env files
+.env.local
+.env.*.local
+
+# Log files
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+__pycache__
+*egg-info
+*pyc

CONTRIBUTING.rst

@@ -0,0 +1,8 @@
+=====================================
+Contributing to Wind Field Visualizer
+=====================================
+
+#. Clone the repository using ``git clone``
+#. Make changes to the code, and commit your changes to a separate branch
+#. Create a fork of the repository on GitHub
+#. Push your branch to your fork, and open a pull request

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause
+
+Copyright (c) 2025, Xuanchen Zhou
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+OF THE POSSIBILITY OF SUCH DAMAGE.

README.rst

@@ -0,0 +1,51 @@
+Wind Field Visualizer
+----------------------------------------
+
+A web-based wind field visualizer
+
+License
+----------------------------------------
+
+This library is OpenSource and follow the BSD License
+
+Installation
+----------------------------------------
+
+Install the application/library
+
+.. code-block:: console
+
+    pip install wind-field-visualizer
+
+Run the application
+
+.. code-block:: console
+
+    wind-field-visualizer
+
+Developement setup
+----------------------------------------
+
+We recommend using uv for setting up and managing a virtual environement for your development.
+
+.. code-block:: console
+
+    # Create venv and install all dependencies
+    uv sync --all-extras --dev
+
+    # Activate environement
+    source .venv/bin/activate
+
+
+    # Allow live code edit
+    uv pip install -e .
+
+
+
+
+Professional Support
+----------------------------------------
+
+* `Training <https://www.kitware.com/courses/trame/>`_: Learn how to confidently use trame from the expert developers at Kitware.
+* `Support <https://www.kitware.com/trame/support/>`_: Our experts can assist your team as you build your web application and establish in-house expertise.
+* `Custom Development <https://www.kitware.com/trame/support/>`_: Leverage Kitware’s 25+ years of experience to quickly build your web application.

bundles/desktop/README.md

@@ -0,0 +1,53 @@
+# Desktop
+
+This relies on [pyinstaller](https://pyinstaller.org/en/stable/) to bundle your trame application into a standalone desktop application.
+
+In our current setup, we'll rely on the current virtual environment to provide the code content.
+
+## Building the bundle
+
+First, run `pip install -r requirements.txt`. This includes `pyinstaller` and `pywebview`, which is required for trame desktop applications.
+
+Next, take a look at the `run.py` file. This should be just a regular python script that starts your trame desktop application. It can be tested via `python run.py`. Due to multiprocessing in some applications, `multiprocessing.freeze_support()` may be required to avoid an infinite recursion of running the script.
+
+Once `python run.py` seems to be working properly, take a look at `create_exe.bat`. This is the pyinstaller command that we will use. Explanations for each option are provided:
+
+1. `--hidden-import vtkmodules.all`: pyinstaller tries to find every dependency, but sometimes it is not able to. You can add additional python dependencies via the `--hidden-import` option, which may be specified multiple times.
+
+For VTK applications, we can include all VTK modules, or to reduce the final binary size, only include the VTK modules that are actually used. The VTK hooks in pyinstaller should be updated in the future so that this is not necessary; see [pyinstaller/pyinstaller-hooks-contrib#327](https://github.com/pyinstaller/pyinstaller-hooks-contrib/issues/327) for details.
+
+2. `--collect-data pywebvue`: normally, pyinstaller will only install python dependencies. For trame, however, we need some javascript files too. Adding this command will get pyinstaller to install the `pywebvue` javascript files as well.
+
+3. `--onefile`: create a single executable for the output. `pyinstaller` by default creates a folder that contains the executable. The single executable is stand-alone and easy to move between computers. The only downside is that it takes a little longer to start and stop compared to the folder executable, because it must unpack itself before starting.
+
+Note: if you are debugging your `pyinstaller` application, consider removing this option. It is much easier to see whether files/folders ended up in the right place in the folder executable mode.
+
+4. `--windowed`: on Mac and Windows, this prevents the terminal/command prompt from being opened when the application is started.
+
+5. `--icon wind-field-visualizer.ico`: the icon file to use for the application.
+
+After running `pyinstaller`, the standalone application may be found inside the `dist` directory that is created.
+
+## MacOS
+
+```bash
+pip install -r ./requirements.txt
+./create_mac.sh
+open ./dist/run.app
+```
+
+## Linux
+
+```bash
+pip install -r ./requirements.txt
+./create_linux.sh
+./dist/run
+```
+
+## Windows
+
+```bash
+pip install -r requirements.txt
+./create_exe.bat
+./dist/run/run.exe
+```

bundles/desktop/create_exe.bat

@@ -0,0 +1,7 @@
+python -m PyInstaller ^
+  --hidden-import pkgutil ^
+  --windowed ^
+  --collect-data trame_vuetify ^
+  --collect-data trame_vtk ^
+  --collect-data trame_client ^
+  .\run.py

bundles/desktop/create_linux.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+python -m PyInstaller \
+    --clean --noconfirm \
+    --hidden-import pkgutil \
+    --collect-data trame_vuetify \
+    --collect-data trame_vtk \
+    --collect-data trame_client \
+    ./run.py

bundles/desktop/create_mac.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+python -m PyInstaller \
+    --clean --noconfirm \
+    --windowed \
+    --hidden-import pkgutil \
+    --collect-data trame_vuetify \
+    --collect-data trame_vtk \
+    --collect-data trame_client \
+    ./run.py

bundles/desktop/requirements.txt

@@ -0,0 +1,2 @@
+pyinstaller
+pywebview

bundles/desktop/run.py

@@ -0,0 +1,7 @@
+import multiprocessing
+
+from wind_field_visualizer.app.main import main
+
+if __name__ == "__main__":
+    multiprocessing.freeze_support()
+    main(exec_mode="desktop")

bundles/docker/DEPLOY.md

@@ -0,0 +1,58 @@
+# Trame deployment
+
+Trame applications can be deployed following different patterns.
+The one describe below is the simplest one and will only scale up to what the hardware is capable of handling.
+For infinite scaling feel free to consult [Kitware](https://www.kitware.com/contact/) for more guidance.
+
+## Docker
+
+This directory provide the core infrastructure for building docker images that can then be deployed your own way.
+But if you are looking for something more Heroku like we suggest using [CapRover](https://caprover.com/).
+
+## Caprover
+
+For that section we will assumed you've setup your own CapRover and you are just aiming to deploy your trame application using the caprover cli from npm.
+
+Before any deployment, you need to create an application from the web interface and check the __Websocket Support__.
+
+Then within the directory that contain this `DEPLOY.md`, you should run the following:
+
+```bash
+rm -rf ./server
+./scripts/build_server.sh
+tar -cvf trame-app.tar captain-definition Dockerfile server
+caprover deploy -t trame-app.tar
+```
+
+It might be necessary to increase the nginx __client_max_body_size__ for your app upload.
+To do that go in: __CapRover > Settings > NGINX Configurations > /etc/nginx/conf.d/captain-root.conf__
+
+
+```json
+# Captain dashboard at captain.captainroot.domain.com
+    server {
+        client_max_body_size 500m;
+```
+
+For GPU access you will need to create a `/etc/docker/daemon.json` with the following content where `GPU-f0ada461` come from the command line below
+
+```bash
+nvidia-smi -a | grep GPU-UUID
+    GPU UUID                              : GPU-f0ada461-5941-6211-dad3-a5003817fb59
+```
+
+=> `/etc/docker/daemon.json`
+```json
+{
+  "runtimes": {
+    "nvidia": {
+      "path": "/usr/bin/nvidia-container-runtime",
+      "runtimeArgs": []
+    }
+  },
+  "default-runtime": "nvidia",
+  "node-generic-resources": [
+    "NVIDIA-GPU=GPU-f0ada461"
+    ]
+}
+```

bundles/docker/Dockerfile

@@ -0,0 +1,11 @@
+FROM kitware/trame:uv
+
+# Set Python and Vue versions
+ENV TRAME_PYTHON=3.13
+ENV TRAME_CLIENT_TYPE=vue3
+
+# Copy the local app and the deploy directory
+COPY --chown=trame-user:trame-user . /local-app
+COPY --chown=trame-user:trame-user ./bundles/docker /deploy
+
+RUN /opt/trame/entrypoint.sh build

bundles/docker/README.md

@@ -0,0 +1,19 @@
+# Docker Bundle
+
+Docker bundle aims to provide an easy step to bundle and deploy your application into a Docker image that can easily be deployed in the cloud as a service and will naturally support multi-users.
+
+## Building the server directory
+
+The **server** directory capture all the key elements of your application and can be used with our generic docker image.
+
+To generate that directory, just run the **scripts/build_server.sh** script.
+
+## Building your docker image
+
+Your docker image is simply bundling the **server** directory into a docker image to simplify possible deployment.
+
+To generate that image, just run the **scripts/build_image.sh** script.
+
+## Running your bundle
+
+Just run either `scripts/run_server.sh` or `scripts/run_image.sh` and open your browser to `http://localhost:8080/wind-field-visualizer.html`

bundles/docker/captain-definition

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 2,
+  "dockerfilePath": "./Dockerfile"
+}

bundles/docker/scripts/build_image.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+CURRENT_DIR=`dirname "$0"`
+
+cd $CURRENT_DIR/../../..
+
+docker build -t wind-field-visualizer -f ./bundles/docker/Dockerfile .

bundles/docker/scripts/run_image.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+docker run -it --rm -p 8080:80 wind-field-visualizer

bundles/docker/setup/apps.yml

@@ -0,0 +1,4 @@
+trame: # Default app under /index.html
+  app: wind-field-visualizer
+wind-field-visualizer: # /wind-field-visualizer.html
+  app: wind-field-visualizer

bundles/docker/setup/initialize.sh

@@ -0,0 +1,2 @@
+# Install app from local directory
+uv pip install /local-app

bundles/docker/setup/requirements.txt

@@ -0,0 +1,2 @@
+# Use published version instead of local-app from initialize.sh
+# wind-field-visualizer

pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "wind-field-visualizer"
+version = "1.0.0"
+description = "A web-based wind field visualizer"
+authors = [
+    {name = "Xuanchen Zhou"},
+]
+dependencies = [
+    "trame>=3.12",
+    "trame-vuetify",
+    "trame-vtk",
+]
+requires-python = ">=3.9"
+readme = "README.rst"
+license = {text = "BSD License"}
+keywords = ["Python", "Interactive", "Web", "Application", "Framework"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "License :: OSI Approved :: BSD License",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.optional-dependencies]
+app = [
+    "pywebview",
+]
+jupyter = [
+    "jupyterlab",
+]
+dev = [
+    "pre-commit",
+    "ruff",
+    "pytest >=6",
+    "pytest-cov >=3",
+    "nox",
+]
+
+[project.scripts]
+wind-field-visualizer = "wind_field_visualizer.app:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[tool.hatch.build]
+include = [
+  "/src/wind_field_visualizer/**/*.py",
+  "/src/wind_field_visualizer/**/*.js",
+  "/src/wind_field_visualizer/**/*.css",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = [
+    "src/wind_field_visualizer",
+]
+
+[tool.ruff]
+
+[tool.ruff.lint]
+extend-select = [
+    "ARG", # flake8-unused-arguments
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "EM",  # flake8-errmsg
+    "EXE", # flake8-executable
+    "G",   # flake8-logging-format
+    "I",   # isort
+    "ICN", # flake8-import-conventions
+    "NPY", # NumPy specific rules
+    "PD",  # pandas-vet
+    "PGH", # pygrep-hooks
+    "PIE", # flake8-pie
+    "PL",  # pylint
+    "PT",  # flake8-pytest-style
+    "PTH", # flake8-use-pathlib
+    "RET", # flake8-return
+    "RUF", # Ruff-specific
+    "SIM", # flake8-simplify
+    "T20", # flake8-print
+    "UP",  # pyupgrade
+    "YTT", # flake8-2020
+]
+ignore = [
+    "PLR09",   # Too many <...>
+    "PLR2004", # Magic value used in comparison
+    "ISC001",  # Conflicts with formatter
+]
+isort.required-imports = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["T20"]
+"noxfile.py" = ["T20"]
+"src/**" = ["SIM117"]

src/wind_field_visualizer/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

src/wind_field_visualizer/app/__init__.py

@@ -0,0 +1,5 @@
+from .main import main
+
+__all__ = [
+    "main",
+]

src/wind_field_visualizer/app/main.py

@@ -0,0 +1,242 @@
+import os
+from trame.app import get_server
+from trame.ui.vuetify import SinglePageLayout
+from trame.widgets import vuetify
+from trame.widgets import vtk as vtk_widget
+import vtk
+import xarray as xr
+import pyvista as pv
+import numpy as np
+
+import matplotlib.pyplot as plt
+from vtkmodules.vtkCommonCore import vtkLookupTable
+
+from vtkmodules.vtkCommonColor import vtkNamedColors
+from vtkmodules.vtkCommonDataModel import vtkPlane
+from vtkmodules.vtkFiltersCore import vtkCutter
+from vtkmodules.vtkFiltersModeling import vtkOutlineFilter
+from vtkmodules.vtkRenderingCore import (
+    vtkActor,
+    vtkPolyDataMapper,
+    vtkRenderer,
+    vtkRenderWindow,
+    vtkRenderWindowInteractor,
+)
+
+def main(server=None, **kwargs):
+    CURRENT_DIRECTORY = os.path.abspath(os.path.dirname(__file__))
+
+    # -----------------------------------------------------------------------------
+    # NetCDF to VTK
+    # -----------------------------------------------------------------------------
+    ds = xr.open_dataset(os.path.join(CURRENT_DIRECTORY, "../../../../../Data/Field_20251119_140509_BuildingGroupFloor.nc"))
+
+    # ----- Load fluid field -----
+    # Vtk uses right-handed coordinate system, while unity uses left-handed coordinate system. So the 
+    # z asix needs to be reversed here.
+    velFieldRaw = ds["velField"][:, ::-1, :, :]
+    nTime, nz, ny, nx, _ = velFieldRaw.shape
+    print(f"Fluid field resolution: {nx=}, {ny=}, {nz=}")
+
+    # ----- Load dx -----
+    velXCoor = ds["velX"]
+    dx = float(velXCoor.values[1] - velXCoor.values[0])
+    print(f"{dx=}")
+
+    # ----- Load dt -----
+    timeList = ds["time"]
+    dt = float(timeList.values[1] - timeList.values[0])
+    dt = round(dt, 2)
+    print(f"{dt=}")
+
+    # ----- Fluid field at the first stored time step -----
+    velField0 = velFieldRaw[0, :, :, :, :3]
+    velFieldMag0 = np.linalg.norm(velField0.values, axis=-1).ravel()
+
+    # ----- Build vtk data -----
+    grid = pv.ImageData()
+    grid.dimensions = (nx, ny, nz)
+    grid.origin = (-(nx-1) * dx / 2, -(ny-1) * dx / 2 + 10, -(nz-1) * dx / 2)
+    grid.spacing = (dx, dx, dx)
+    grid.point_data["vel_mag"] = velFieldMag0
+
+    vtk_producer = vtk.vtkTrivialProducer()
+    vtk_producer.SetOutput(grid)
+
+    # -----------------------------------------------------------------------------
+    # PLY Reader (for building model)
+    # -----------------------------------------------------------------------------
+
+    modelReader = vtk.vtkPLYReader()
+    # modelReader.SetFileName("Data/SmallBuilding3.ply")
+    modelReader.SetFileName(os.path.join(CURRENT_DIRECTORY, "../../../../Data/Buildings-GroupAll.ply"))
+    modelReader.Update()
+
+    modelMapper = vtk.vtkPolyDataMapper()
+    modelMapper.SetInputConnection(modelReader.GetOutputPort())
+
+    modelActor = vtk.vtkActor()
+    modelActor.SetMapper(modelMapper)
+
+    transform = vtk.vtkTransform()
+
+    transform.PostMultiply()
+
+    # Small building 3
+    # transform.RotateX(-90.0)
+    # transform.RotateY(50.0)
+
+    # Building Group
+    transform.Translate(25, 0.2, -12)
+    transform.RotateX(180.0)
+    transform.RotateY(180.0)
+
+    modelActor.SetUserTransform(transform)
+
+    # -----------------------------------------------------------------------------
+    # Render VTK fluid field
+    # -----------------------------------------------------------------------------
+
+    renderer = vtkRenderer()
+    renderWindow = vtkRenderWindow()
+    renderWindow.AddRenderer(renderer)
+
+    renderWindowInteractor = vtkRenderWindowInteractor()
+    renderWindowInteractor.SetRenderWindow(renderWindow)
+    renderWindowInteractor.GetInteractorStyle().SetCurrentStyleToTrackballCamera()
+
+    # ----- Render outline -----
+
+    colors = vtkNamedColors()
+
+    outline = vtkOutlineFilter()
+    outline.SetInputConnection(vtk_producer.GetOutputPort())
+
+    outlineMapper = vtkPolyDataMapper()
+    outlineMapper.SetInputConnection(outline.GetOutputPort())
+
+    outlineActor = vtkActor()
+    outlineActor.SetMapper(outlineMapper)
+    outlineActor.GetProperty().SetColor(colors.GetColor3d("White"))
+
+    # ----- Colormap -----
+    def create_vtk_lut_from_matplotlib(cmap_name, num_colors=256):
+        mpl_cmap = plt.get_cmap(cmap_name)
+        
+        lut = vtkLookupTable()
+        lut.SetNumberOfTableValues(num_colors)
+        
+        for i in range(num_colors):
+            rgba = mpl_cmap(i / (num_colors - 1))
+            lut.SetTableValue(i, rgba[0], rgba[1], rgba[2], 1.0)
+        
+        lut.SetRange(0, 15) 
+        lut.Build()
+        return lut
+
+    turbo_lut = create_vtk_lut_from_matplotlib("turbo")
+
+    # ----- Render a slice -----
+    center_x = grid.center[0]
+    center_y = grid.center[1]
+    center_z = grid.center[2]
+    plane = vtkPlane()
+    plane.SetOrigin(center_x, center_y, center_z)
+    plane.SetNormal(0, 1, 0)
+    print(f"{grid.center[1]=}")
+
+    cutter = vtkCutter()
+    cutter.SetInputConnection(vtk_producer.GetOutputPort())
+    cutter.SetCutFunction(plane)
+    cutter.Update()
+
+    slice_mapper = vtkPolyDataMapper()
+    slice_mapper.SetInputConnection(cutter.GetOutputPort())
+    slice_mapper.SetScalarModeToUsePointFieldData()
+    slice_mapper.SelectColorArray("vel_mag")
+    slice_mapper.SetLookupTable(turbo_lut)
+    slice_mapper.SetScalarRange(0, 15)
+
+    slice_actor = vtkActor()
+    slice_actor.SetMapper(slice_mapper)
+
+    # Add the actors to the renderer
+    renderer.AddActor(outlineActor)
+    renderer.AddActor(slice_actor)
+    renderer.AddActor(modelActor)
+    renderer.ResetCamera()
+    renderWindow.Render()
+
+    # -----------------------------------------------------------------------------
+    # GUI
+    # -----------------------------------------------------------------------------
+
+    server = get_server(client_type = "vue2")
+    ctrl = server.controller
+    state = server.state
+
+    @state.change("time")
+    def update_time(time, **kwargs):
+        time_index = round(time / dt) - 1
+        newVelField = velFieldRaw[time_index, :, :, :, :3]
+        newVelMagFlat = np.linalg.norm(newVelField.values, axis=-1).ravel()
+        grid.point_data["vel_mag"] = newVelMagFlat
+        grid.Modified()
+        ctrl.view_update()
+
+    @state.change("ypos")
+    def update_ypos(ypos, **kwargs):
+        plane.SetOrigin(center_x, ypos, center_z)
+        ctrl.view_update()
+
+    def reset_ypos():
+        state.ypos = center_y
+
+    with SinglePageLayout(server) as layout:
+        layout.title.set_text("Fluid Field Visualizer")
+
+        with layout.toolbar:
+            vuetify.VSpacer()
+
+            # Time slider
+            vuetify.VSlider(
+                label="Time (s)",
+                v_model=("time", 0),
+                min=dt,
+                max=nTime * dt,
+                step=dt,
+                thumb_label=True,
+                hide_details=True,
+                dense=True,
+                style="max-width: 300px; margin-top: 40px; margin-bottom: 10px;",
+            )
+            vuetify.VDivider(vertical=True, classes="mx-2")
+
+            # Slice position silder
+            vuetify.VSlider(
+                label="Y Position (m)",
+                v_model=("ypos", center_y),
+                min=grid.bounds[2] + dx, 
+                max=grid.bounds[3] - dx, 
+                step=dx,
+                thumb_label=True,
+                hide_details=True, 
+                dense=True,
+                style="max-width: 300px; margin-top: 40px; margin-bottom: 10px;",
+            )
+            with vuetify.VBtn(icon=True, click=reset_ypos):
+                vuetify.VIcon("mdi-restore")
+            vuetify.VDivider(vertical=True, classes="mx-2")
+
+        with layout.content:
+            with vuetify.VContainer(
+                fluid=True,
+                classes="pa-0 fill-height",
+            ):
+                view = vtk_widget.VtkLocalView(renderWindow)
+                ctrl.view_update = view.update
+
+    server.start()
+
+if __name__ == "__main__":
+    main()