Metadata-Version: 2.5
Name: trame-rca
Version: 2.12.0
Summary: Remote Controlled Area widget for trame
Author: Kitware Inc.
License: Apache License 2.0
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.10
Requires-Dist: numpy
Requires-Dist: packaging
Requires-Dist: pillow
Requires-Dist: trame-client<5,>=3.4
Requires-Dist: trame-common>=1.2.2
Requires-Dist: wslink>=2.1.3
Provides-Extra: avif
Requires-Dist: pillow-avif-plugin; extra == 'avif'
Provides-Extra: dev
Requires-Dist: pixelmatch; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-benchmark; extra == 'dev'
Requires-Dist: pytest-playwright; extra == 'dev'
Requires-Dist: pytest-xprocess; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: trame-vuetify>=3.2.6; extra == 'dev'
Requires-Dist: trame>=4; extra == 'dev'
Provides-Extra: turbo
Requires-Dist: pyturbojpeg; extra == 'turbo'
Provides-Extra: vtkstreaming
Requires-Dist: vtk; extra == 'vtkstreaming'
Requires-Dist: vtk-streaming>=0.4.0; extra == 'vtkstreaming'
Description-Content-Type: text/x-rst

.. |pypi_download| image:: https://kitware.github.io/trame/downloads/trame-rca.svg

=============================================
Remote Controlled Area |pypi_download|
=============================================

Remote Controlled Area widget for trame provide components
and communication infrastructure to display remote generated
image based content while allowing interaction forwarding
such as mouse, touch and multi-pointer devices.

This library aims to provide a core that can then be extended
or specialized for any backend. But its initial integration
will be focused toward VTK and/or ParaView for enabling
interactive remote rendering.
But because it aims to be generic, you should be able to rely
on its core to connect and drive any kind of backend that could
produce images/video-stream and react to mouse interaction.

License
-----------------------------------------------------------

trame-rca is made available under the Apache Software License.


Development
-----------------------------------------------------------

The client-side code is split into a framework-agnostic core (``js-components``)
and Vue/React adapters that depend on it. Install and build the core first, then
the adapter(s) you need.

.. code-block:: console

    cd js-components
    npm i

    cd ../vue-components
    npm i
    npm run build

    # optional React adapter
    cd ../react-components
    npm i
    npm run build

    cd -

Install the component

.. code-block:: console

    uv sync --all-extras --dev


Optional dependencies
-----------------------------------------------------------

TurboJPEG
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Faster Jpeg encoding using TurboJPEG.

**macOS system install**

.. code-block:: console

    # macOS
    brew install jpeg-turbo

**Windows install**

Download and install from Github: https://github.com/libjpeg-turbo/libjpeg-turbo/releases

**Linux install**

.. code-block:: console

    # RHEL/CentOS/Fedora
    # YUM doc: https://libjpeg-turbo.org/Downloads/YUM

    # Ubuntu: its libturbojpeg package is 2.x (2.1.5 on 24.04), but PyTurboJPEG 2
    # needs libjpeg-turbo >= 3.0, so install the official package from
    # https://github.com/libjpeg-turbo/libjpeg-turbo/releases
    sudo apt install ./libjpeg-turbo-official_<version>_<arch>.deb  # amd64 or arm64

Once your system is ready, you can try our code example:

.. code-block:: console

    pip install trame trame-vuetify vtk
    pip install "trame-rca[turbo]"

    # other encoders: jpeg, avif, turbo-jpeg, png, webp
    python ./examples/01_vtk/vtk_cone_simple.py --encoder turbo-jpeg

Video encoding with VTKStreaming
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

VTKStreaming provides tools for encoding and streaming frames from a VTK OpenGL render window using video codecs.
When NVENC is available, it enables H.264/H.265 hardware encoding; otherwise, software encoding falls back to VP9 via libvpx.

The codec is negotiated when the ``video-decoder`` display mounts: the client asks the server which codecs it can encode
(``trame.rca.video.codecs``), filters them with ``VideoDecoder.isConfigSupported``, and sends the accepted list back
(``trame.rca.video.negotiate``). The server then creates the encoder with ``vtkEncoderFactory`` preferences
``Hardware=true;Codec=<accepted list>``. No frames are pushed before negotiation. Pass ``on_video_codec`` to
``create_view_handler`` to be told what was selected (``codec``, ``backend``, ``hardware``, ``label`` or ``error``).

You can try our code example:

.. code-block:: console

    pip install trame trame-vuetify vtk
    pip install "trame-rca[vtkstreaming]"

    python ./examples/05_video/vtk_cone_simple_video.py

In order to use source-build of vtkstreaming, please clone [VTKStreaming](https://github.com/Kitware/VTKStreaming.git) one level
up outside the trame-rca directory, checkout the `wheel` branch, and install it inside the trame-rca virtual environment

.. code-block:: console

    cd ..
    git clone https://github.com/Kitware/VTKStreaming.git
    cd VTKstreaming
    uv pip install --group dev          # build deps into active venv; index from tool.uv.index
    uv pip install -e . --no-build-isolation
    cd ../trame-rca

    python ./examples/05_video/vtk_cone_simple_video.py

Shared textures with Electron
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In an Electron app, VTK can render into a GPU texture that Electron shows as is: without encoding
and without copying to the CPU. The Electron side is the ``@kitware/trame-rca-electron`` npm package in
``./js-electron-lib``: it starts the trame server and loads its page. Supported on macOS (IOSurface),
Windows (D3D11 NT handles) and Linux under Wayland (dma-buf).

- macOS: works out of the box (IOSurface).
- Windows: the GL driver needs ``WGL_NV_DX_interop2``, and VTK must render on the GPU
  Chromium uses. Set ``D3D_ADAPTER=<index>`` if that isn't DXGI adapter 0.
- Linux: Wayland only for now (dma-buf). Electron duplicates the server's file descriptors
  with ``pidfd_getfd``, which needs ``kernel.yama.ptrace_scope`` at 1 or less:
  ``sudo sysctl -w kernel.yama.ptrace_scope=1``. Set ``RENDER_NODE=/dev/dri/renderD129``
  if VTK picks another GPU than the compositor.
- Linux: if Electron fails to start with ``The SUID sandbox helper binary was found, but is
  not configured correctly``, allow unprivileged user namespaces. On Ubuntu 24.04 and later:
  ``sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0``. On older distributions:
  ``sudo sysctl -w kernel.unprivileged_userns_clone=1``.

.. code-block:: python

    # before creating any VTK render window,
    # this setup environment to properly initialize
    # VTK factories to work with Electron native textures.
    import trame_rca.electron.vtk

    from trame.widgets import rca

    # ... create render_window, then in the UI:
    view = rca.RemoteControlledArea(display="shared-texture")
    view_handler = view.create_electron_handler(render_window)

You can try our code example:

.. code-block:: console

    uv venv
    uv pip install trame trame-vuetify trame-rca vtk
    source .venv/bin/activate

    cd examples/06_electron_apps/electron
    npm i
    npm start

See ``js-electron-lib/README.md`` for the Electron API and what packaging an app needs.
