Metadata-Version: 2.3
Name: jupyterlab-trame-manager
Version: 0.6.0
Dynamic: Keywords
Summary: A JupyterLab extension.
Project-URL: Homepage, https://github.com/jwindgassen/jupyterlab-trame-manager
Project-URL: Bug Tracker, https://github.com/jwindgassen/jupyterlab-trame-manager/issues
Project-URL: Repository, https://github.com/jwindgassen/jupyterlab-trame-manager.git
Author-email: Jonathan Windgassen <j.windgassen@fz-juelich.de>
License: BSD 3-Clause License
        
        Copyright (c) 2023, Forschungszentrum Jülich GmbH
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. 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.
        
        3. 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.
License-File: LICENSE
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: jupyter-server-proxy>=4.1
Requires-Dist: jupyter-server<3,>=2.0.1
Description-Content-Type: text/markdown

# jupyterlab-trame-manager

[![Github Actions Status](https://github.com/jwindgassen/jupyterlab-trame-manager/workflows/Build/badge.svg)](https://github.com/jwindgassen/jupyterlab-trame-manager/actions/workflows/build.yml)

**jupyterlab-trame-manager** (previously known as **jupyter-viz-extension** or **JuViz**) is an extension for JupyterLab that enables the usage of [ParaView trame](https://kitware.github.io/trame/)
within JupyterLab. It bridges Cloud and interactive Visualization, allowing users to run and control their customized
visualization and analysis apps, written in trame, from inside the JupyterLab.
It was written with Cloud-Computing and HPC in mind and is designed to be platform-independant.

## Installation and Configuration

#### Requirements

For the extension, you only need 2 Components:

- JupyterLab >= 3.0
- JupyterServerProxy >= 3

The extension itself is not linked to any trame dependencies, as these are loaded at runtime when the app is launched.

#### Installation

To install the extension, execute:

```bash
pip install jupyterlab_trame_manager
```

#### Configuration

The extension can be configured with different `Configuration` classes. These contain the platform/architecture specific code
and can be used to configure how ParaView and trame Instances are launched, where trame app configs are stored, etc.
The `Configuration` class is selected at runtime via the `TRAME_MANAGER_CONFIGURATION` environment variable.

Existing `Configuration`s can be found in [the configurations sub-package](./jupyterlab_trame_manager/configurations)

To start correctly, set the `TRAME_MANAGER_CONFIGURATION` environment variable before starting JupyterLab:

```bash
export TRAME_MANAGER_CONFIGURATION=desktop
```

## Adding a trame app to the extension

To add a trame app to the Extension that can be configured and executed in JupyterLab, you need to:

1. Copy the App and all its Assets and required Files, to the Cluster.
   - By default, it will look at all locations in the `JUPYTER_PATH` environment variable and try to detect apps that are in the `trame` subdirectory.
   - In most cases, `~/.local/share/jupyter/trame` is a valid location for alls
   - Put your trame app in a new subdirectory in the `trame` forder. For example: `~/.local/share/jupyter/trame/my-app`
2. You now need to tell the Extension some details about your app and how it should be launched:
   - Create a file called `app.yml` with the following values:
     - _name_: Display name of the App that is used in the UI
     - _working_directory_: The working directory of a launched instance, i.e., from where the launch command should be executed
     - _command_: The launch command to execute. This should: load all dependencies, prepare the environment and launch the app.
   - The launch command will be passed some arguments for trame, which are generated by the extension before the launch (authentication key, etc.)
     in the `TRAME_INSTANCE_ARGS` variable. These must be forwarded to trame when the app is started: `python my-app/__init__.py $TRAME_INSTANCE_ARGS`

Thats it! Now your app should be available and launchable in the UI.

## Connect a trame app to a ParaView Server

ToDo

## Creating a custom Configuration

To create a new `Configuration` for a new system, create a new Python file in the _configurations_ sub-package and
create a new class that inherits from `jupyterlab_trame_manager.configurations.Configuration` (or any other `Configuration` if desired).
Here you can override exiting methods of the class and customize, how things are executed. Take a look at the doc-strings
of the base `Configuration` class for a more detailed explanation.

## Contributing

### Development install

Note: You will need NodeJS to build the extension package.

The `jlpm` command is JupyterLab's pinned version of [yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use `yarn` or `npm` in lieu of `jlpm` below.

```bash
pip install -e "."
jupyter labextension develop . --overwrite
jupyter server extension enable jupyterlab_trame_manager
jlpm build
```

You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.

```bash
jlpm watch
# Run JupyterLab in another terminal
jupyter lab
```

With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).
