trame-vtkjs 0.1.0__tar.gz

trame_vtkjs-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+.DS_Store
+build
+node_modules
+.venv
+.venv-pv
+.pyvista
+/.vite/
+/dist/
+
+bike.vtp
+seeds.jpg
+tunnel.vtu
+
+.coverage
+dev
+.dev-seb.md
+visual_baseline/**/*.txt
+visual_baseline/**/baseline.png
+visual_baseline/**/baseline_diff_*
+
+# 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

trame_vtkjs-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+Create a branch for your change and follow [build and test](docs/development.md).
+Install the configured checks with `python -m pip install pre-commit`, then run
+`pre-commit install` and `pre-commit run --all-files`.
+
+Use Conventional Commits, such as `feat: add a view option` or
+`fix: repair scene recovery`. CI checks the incoming messages, and release-causing
+commits select versions when merged to `main`. See [release rules](docs/releases.md).
+
+Open a pull request with a concrete description of the behavior being changed.

trame_vtkjs-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+Apache Software License 2.0
+
+Copyright (c) 2024, Kitware Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

trame_vtkjs-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: trame-vtkjs
+Version: 0.1.0
+Summary: vtk.js scene replication and shared-context rendering for trame
+Project-URL: Repository, https://github.com/PaulHax/trame-vtkjs
+Project-URL: Issues, https://github.com/PaulHax/trame-vtkjs/issues
+Author: Kitware Inc., Paul Elliott
+License: Apache Software License
+License-File: LICENSE
+Keywords: Application,Framework,Interactive,Python,Web
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: trame
+Requires-Dist: trame-common
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: trame-client[test]; extra == 'dev'
+Provides-Extra: vtk
+Requires-Dist: vtk<9.7,>=9.6; extra == 'vtk'
+Description-Content-Type: text/markdown
+
+# trame-vtkjs
+
+Render Python VTK scenes in the browser with vtk.js. The Python server and
+browser client ship together in one wheel, with scene updates, picking,
+streaming, and recovery across connected clients.
+
+| View | Rendering context |
+| --- | --- |
+| `VtkJsLocalView` | Own canvas and camera controls |
+| `VtkJsSharedView` | Host-owned WebGL context, including MapLibre |
+
+## Install and try it
+
+Install a wheel built from this repository or downloaded from its releases:
+
+```sh
+python -m pip install "./dist/trame_vtkjs-<version>-py3-none-any.whl[vtk]"
+```
+
+The `vtk` extra installs the supported VTK 9.6 series. The Python namespace is
+`trame_vtkjs`; application widgets are available through trame:
+
+```python
+from trame.widgets.vtkjs import VtkJsLocalView, VtkJsSharedView
+```
+
+From the checkout, run the interactive cone example:
+
+```sh
+python examples/vtk/vtkjs_cone.py
+```
+
+The [MapLibre example](https://github.com/PaulHax/trame-vtkjs/blob/main/examples/vtk/maplibre_demo/README.md) combines shared
+rendering, textures, editable landmarks, and streamed geometry.
+
+## Documentation
+
+- [API and rendering contracts](https://github.com/PaulHax/trame-vtkjs/blob/main/docs/api.md)
+- [Build and test](https://github.com/PaulHax/trame-vtkjs/blob/main/docs/development.md)
+- [Releases and publisher setup](https://github.com/PaulHax/trame-vtkjs/blob/main/docs/releases.md)
+- [Contributing](https://github.com/PaulHax/trame-vtkjs/blob/main/CONTRIBUTING.md)
+
+Licensed under [Apache 2.0](https://github.com/PaulHax/trame-vtkjs/blob/main/LICENSE), retaining Kitware's copyright and
+attribution. Maintained by Paul Elliott.

trame_vtkjs-0.1.0/README.md

@@ -0,0 +1,44 @@
+# trame-vtkjs
+
+Render Python VTK scenes in the browser with vtk.js. The Python server and
+browser client ship together in one wheel, with scene updates, picking,
+streaming, and recovery across connected clients.
+
+| View | Rendering context |
+| --- | --- |
+| `VtkJsLocalView` | Own canvas and camera controls |
+| `VtkJsSharedView` | Host-owned WebGL context, including MapLibre |
+
+## Install and try it
+
+Install a wheel built from this repository or downloaded from its releases:
+
+```sh
+python -m pip install "./dist/trame_vtkjs-<version>-py3-none-any.whl[vtk]"
+```
+
+The `vtk` extra installs the supported VTK 9.6 series. The Python namespace is
+`trame_vtkjs`; application widgets are available through trame:
+
+```python
+from trame.widgets.vtkjs import VtkJsLocalView, VtkJsSharedView
+```
+
+From the checkout, run the interactive cone example:
+
+```sh
+python examples/vtk/vtkjs_cone.py
+```
+
+The [MapLibre example](https://github.com/PaulHax/trame-vtkjs/blob/main/examples/vtk/maplibre_demo/README.md) combines shared
+rendering, textures, editable landmarks, and streamed geometry.
+
+## Documentation
+
+- [API and rendering contracts](https://github.com/PaulHax/trame-vtkjs/blob/main/docs/api.md)
+- [Build and test](https://github.com/PaulHax/trame-vtkjs/blob/main/docs/development.md)
+- [Releases and publisher setup](https://github.com/PaulHax/trame-vtkjs/blob/main/docs/releases.md)
+- [Contributing](https://github.com/PaulHax/trame-vtkjs/blob/main/CONTRIBUTING.md)
+
+Licensed under [Apache 2.0](https://github.com/PaulHax/trame-vtkjs/blob/main/LICENSE), retaining Kitware's copyright and
+attribution. Maintained by Paul Elliott.

trame_vtkjs-0.1.0/docs/api.md

@@ -0,0 +1,114 @@
+# API and rendering contracts
+
+## Python imports
+
+```python
+from trame.widgets.vtkjs import VtkJsLocalView, VtkJsSharedView
+from trame_vtkjs import (
+    PointCloudSource, StreamedSceneActor, Tiles3DSource,
+    Tiles3DQualityPolicy, Tiles3DTexturePolicy,
+)
+from trame_vtkjs.interaction import make_pickable, clear_pickable, PickPreview
+from trame_vtkjs.projected_texture import (
+    MODE_HOMOGRAPHY, MODE_WORLD_TO_CLIP,
+    mark_projected_texture, set_projected_texture_matrix,
+)
+from trame_vtkjs.screen_size_glyphs import mark_screen_size_glyphs
+from trame_vtkjs.streamed_scene import DEFAULT_ADAPTIVE_MIN_BUDGET, source_block
+from trame_vtkjs.streamed_scene_blocks import AdaptiveOptions, Presentation
+```
+
+The helper modules also expose configuration types and readers.
+`streamed_scene_blocks` describes the JSON feature blocks; `view_types` contains
+view policy types. Application code should use these supported modules and
+widgets rather than importing from the view implementation.
+
+## Views and browser access
+
+`VtkJsLocalView` renders on its own canvas. `VtkJsSharedView` renders in a
+host-owned WebGL context; the host controls its canvas, camera, and interaction.
+Both accept a Python `vtkRenderWindow`.
+
+The Vue plugin `trame_vtkjs` exports `install`, `VtkJsLocal`, and `VtkJsShared`.
+Their element names are `vtk-js-local` and `vtk-js-shared`. Browser hosts resolve
+mounted views through `window.trameVtkjs.getView(key)` or `whenView(key)`, and
+access the shared matrix helpers through `window.trameVtkjs.glMatrix`.
+`trame.modules.vtkjs` exposes module registration and serves the browser runtime
+under `__trame_vtkjs`. Scene replication uses protocol v2 with `scene.ops` and
+`scene.resync`.
+
+## Publish and recover
+
+Use `view.transaction()` to publish batched VTK mutations and commands together
+when the context exits. Use `view.sync()` to flush other pending changes.
+Replaced datasets, properties, transforms, and pipeline
+connections are tracked automatically. Publication also checks pipeline and
+transform MTimes because some VTK operations omit `ModifiedEvent`.
+
+After bypassing VTK modification notifications, call `view.recover()` to scan
+MTimes and publish missed changes. Browser resynchronization performs recovery
+before returning a snapshot. A serialization failure preserves pending changes
+and command order for a later retry.
+
+## Streaming policies
+
+Both views accept these construction options:
+
+| Option | Default | Alternatives |
+| --- | --- | --- |
+| `tiles3d_texture_policy` | `"auto"` | `"native"`, `"rgba"` |
+| `tiles3d_quality_policy` | `"adaptive"` | `"fixed"` |
+| `streamed_memory_budget_bytes` | Browser-derived | A page-wide byte allowance |
+
+Automatic texture policy chooses native compression, except for software
+renderers and headless browsers, which use RGBA. Views on one page share a memory
+allowance and must receive the same value. It covers resident streamed geometry
+and textures, not total browser memory or reserved GPU memory. Changing it
+requires a page reload.
+
+## External-resource gates
+
+Shared views expose `registerSceneGate(hold)` and `retrySceneGate()`.
+`hold(message)` receives an in-order scene message and returns `true` to delay
+it, for example until matching video pixels arrive. A later message that is not
+held first releases the queued messages, then applies itself. Global sequence
+order is preserved, even if the held resources are still missing.
+Call `retrySceneGate()` when the
+resource arrives. A held message applies after three seconds even if its gate
+still holds it; request missing resources before that deadline. Snapshots are
+never held. Disposing a registration releases its held messages.
+
+## Picking and drag acknowledgement
+
+Gesture `pointer_event` camera matrices and `setRenderedCamera` use column-major
+layout in both views. Drag start, move, and end events share an opaque
+`gesture_id`. The browser keeps its final preview until the originating view
+acknowledges the release after publishing the final scene mutations:
+
+```python
+view.send_command("pointer.drag.end", {"gesture_id": event["gesture_id"]})
+```
+
+Send this command even for unchanged, cancelled, or rejected drops, using
+`finally` when a handler can exit early. Do not retain it. Async handlers must
+await scene mutations before acknowledging. The ordered acknowledgement makes
+the server position authoritative.
+
+For points that move between render buckets, use the same nonempty
+`preview_group` in `make_pickable` for every bucket in a layer. IDs must be unique
+within the group, using one coordinate system and preview mode. Give independent
+layers distinct groups. Previews follow `(preview_group, point_id)` across
+buckets; duplicate IDs or removed targets stop them safely. Points keep
+independent pending previews, and a regrab transfers its point to the new gesture.
+
+## Point mapper limits
+
+For direct `vtkPointGaussianMapper` scenes, explicitly call
+`mapper.SetScaleFactor(0)` to select simple points. Nonzero scale factors,
+anisotropy, Gaussian arrays/functions, rotations, and custom splat shaders raise
+translation errors. `Emissive` and `BoundScale` are not forwarded in this mode.
+
+Point size comes from the actor property. The direct-cloud presentation block
+uses vtk.js `pointSizeScale` for CSS pixels without changing `scaleFactor`.
+Streamed scenes construct their mappers in the browser and control the resident
+draw prefix there.

trame_vtkjs-0.1.0/docs/development.md

@@ -0,0 +1,70 @@
+# Build and test
+
+Use Python 3.10 and Node.js 24 for development, matching CI. Work from the
+repository root with npm available. The browser
+bundle needs the exact vtk.js commit in [`vtkjs-fork.env`](../vtkjs-fork.env).
+
+## Build the renderer and browser client
+
+```sh
+bridge_root="$PWD"
+source ./vtkjs-fork.env
+vtkjs_build="$(dirname "$bridge_root")/vtk-js-build"
+git clone "$VTKJS_FORK_REPO" "$vtkjs_build"
+git -C "$vtkjs_build" checkout --detach "$VTKJS_FORK_COMMIT"
+(
+  cd "$vtkjs_build"
+  npm ci
+  npm run build:esm
+  cd dist/esm
+  npm link
+)
+(
+  cd "$bridge_root/vue-components"
+  npm ci
+  npm link @kitware/vtk.js
+  npm run build
+)
+```
+
+Use an existing clean renderer checkout at the pinned commit if one is available.
+The `tiled-vtkjs` dependency must come from its integrity-checked lockfile,
+not a linked development tree. Rebuild the browser client after changing its
+source; Python serves the built files.
+
+## Install development dependencies
+
+```sh
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[vtk,dev]" -r tests/requirements.txt
+```
+
+## Run checks
+
+```sh
+(cd vue-components && npm test)
+python -m pytest -m "not js_oracle" \
+  --ignore=tests/push_oracle_e2e --ignore=tests/test_shared_gl_context.py
+python -m playwright install chromium
+python -m pytest tests/test_shared_gl_context.py tests/push_oracle_e2e \
+  tests/test_module_assets_e2e.py --browser chromium
+```
+
+Browser checks run headless by default. MapLibre checks additionally need local
+vendor files; see the [example guide](../examples/vtk/maplibre_demo/README.md).
+Headless runs establish correctness, not hardware performance.
+
+## Build distributable artifacts
+
+From committed source, with the renderer link available:
+
+```sh
+./release.sh build
+./release.sh verify
+```
+
+The script installs the locked browser dependencies, rebuilds the served client
+and streaming codecs, and verifies wheel/sdist contents and dependency revisions.
+Artifacts and evidence go in `dist/`. These commands publish nothing. See
+[releases](releases.md) for public versions and publisher setup.

trame_vtkjs-0.1.0/docs/releases.md

@@ -0,0 +1,74 @@
+# Releases
+
+The [workflow](../.github/workflows/release.yml) checks incoming commits, builds
+and tests distributions, then publishes release-causing `main` changes to GitHub
+Releases and PyPI. It uses Python Semantic Release's parser and version algorithm.
+
+## Commit rules
+
+| Commit | Version change |
+| --- | --- |
+| `feat: ...` | Minor |
+| `fix: ...`, `perf: ...` | Patch |
+| `type!: ...` or a `BREAKING CHANGE:` footer | Minor before 1.0; major thereafter |
+| Ordinary docs, maintenance, tests, refactors | No release |
+
+CI validates every incoming non-merge commit. Prefer rebase merging to preserve
+the validated messages; squash merges also need a valid final message. To check
+one locally, install `requirements-release.txt` and run:
+
+```sh
+python release_plan.py lint --message-file PATH
+```
+
+The first product version is `0.1.0`; tags use `trame-vtkjs-vX.Y.Z`. The baseline
+in `pyproject.toml` excludes inherited history from initial message validation
+and version calculation. No generated version/changelog commit changes the
+source revision after testing.
+
+## Publisher setup
+
+Keep Actions disabled while seeding the new repository. Its initial `main` must
+already contain the exact `baseline_commit` configured in `pyproject.toml`,
+including the identity rename and its shipping ancestry. Open the release/docs
+PR from that baseline, and rebase only the commits after it. Rebase-merging the
+entire migration from an earlier shipping commit would rewrite the required
+baseline and prevent release planning. The initial seed therefore includes the
+identity rename; review it before authorizing that push. Preserve the old
+repository's tags/assets for existing wheel URLs. Enable Actions only when
+the release-capable merge is intended to publish.
+
+Register a PyPI [pending trusted publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+or update an existing project's publisher with these fields:
+
+| Field | Value |
+| --- | --- |
+| PyPI project | `trame-vtkjs` |
+| GitHub owner / repository | `PaulHax` / `trame-vtkjs` |
+| Workflow filename | `release.yml` |
+| Environment | `pypi` |
+
+Create the matching GitHub environment, allow `main` releases, and configure
+branch protection and merge settings. Build jobs have read-only repository
+access. Only the GitHub release job has `contents: write`; only the separate
+PyPI job has `id-token: write`. No PyPI token is stored in the repository.
+
+## Artifacts and recovery
+
+A source-bound plan selects the public version before building. CI verifies
+that the wheel and sdist contain identical runtime files, installs/tests the
+wheel, and transfers those artifacts to publication jobs. Those jobs do not
+rebuild source. Evidence records source/tree, upstream pins, and artifact hashes.
+
+Existing GitHub assets and PyPI digests must match the tested bytes. Exact-byte
+reruns stage only missing distributions; conflicts require a new source change
+and version. Rerun failed publication jobs with their retained artifacts to
+complete a partial release. Main releases are serialized, and stale plans stop
+publication. Registry races fail safely and are checked again on a rerun.
+
+Local builds use `0.1.0+git.<sha>`. A public build receives
+`TRAME_VTKJS_RELEASE_VERSION=X.Y.Z` from `release_plan.py`; its sdist preserves
+that version and built browser assets without requiring Git or npm at install.
+See [build and test](development.md) for non-publishing commands. Release-tool
+updates require contract tests and workflow validation. Full MapLibre/recovery
+qualification remains separate from CI's headless shared-GL/codec smoke gate.

trame_vtkjs-0.1.0/hatch_build.py

@@ -0,0 +1,89 @@
+"""Resolve public release, source distribution and development versions.
+
+Release builds provide ``TRAME_VTKJS_RELEASE_VERSION`` as a public ``X.Y.Z``
+version. Source distributions retain that version in ``PKG-INFO`` so installing
+them requires neither Git nor a release environment. Development checkouts use
+``<BASE_VERSION>+git.<short-sha>``. Exact source provenance lives in the bundled
+build metadata for both public and development wheels.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from email.parser import Parser
+from pathlib import Path
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+from packaging.utils import canonicalize_name
+from packaging.version import InvalidVersion, Version
+
+# Development versions retain a readable base independently of release tags.
+BASE_VERSION = "0.1.0"
+LOCAL_LABEL = "git"
+PUBLIC_VERSION = re.compile(r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)")
+
+
+def _release_version() -> str | None:
+    version = os.environ.get("TRAME_VTKJS_RELEASE_VERSION")
+    if version is not None and not PUBLIC_VERSION.fullmatch(version):
+        raise ValueError("TRAME_VTKJS_RELEASE_VERSION must be a public X.Y.Z version")
+    return version
+
+
+def _sdist_version(root: str) -> str | None:
+    path = Path(root) / "PKG-INFO"
+    if not path.is_file():
+        return None
+    metadata = Parser().parsestr(path.read_text(encoding="utf-8"))
+    if canonicalize_name(metadata.get("Name", "")) != "trame-vtkjs":
+        raise ValueError("PKG-INFO does not identify the trame-vtkjs distribution")
+    version = metadata.get("Version", "")
+    try:
+        return str(Version(version))
+    except InvalidVersion as error:
+        raise ValueError("PKG-INFO must contain a valid package version") from error
+
+
+def _short_sha(root: str) -> str | None:
+    sha = os.environ.get("TRAME_VTKJS_SHA")
+    if sha:
+        return sha.strip()
+    try:
+        toplevel = subprocess.check_output(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=root,
+            stderr=subprocess.DEVNULL,
+        )
+        if Path(toplevel.decode().strip()).resolve() != Path(root).resolve():
+            return None
+        out = subprocess.check_output(
+            ["git", "rev-parse", "--short", "HEAD"],
+            cwd=root,
+            stderr=subprocess.DEVNULL,
+        )
+    except (OSError, subprocess.CalledProcessError):
+        return None
+    return out.decode().strip() or None
+
+
+def _stamped_version(root: str) -> str:
+    release = _release_version()
+    if release is not None:
+        return release
+    archived = _sdist_version(root)
+    if archived is not None:
+        return archived
+    sha = _short_sha(root)
+    if not sha:
+        raise ValueError(
+            "Package version requires a Git checkout, sdist PKG-INFO, or "
+            "TRAME_VTKJS_RELEASE_VERSION"
+        )
+    return f"{BASE_VERSION}+{LOCAL_LABEL}.{sha}"
+
+
+class ShaVersionMetadataHook(MetadataHookInterface):
+    def update(self, metadata: dict) -> None:
+        metadata["version"] = _stamped_version(self.root)