Plugin/App development guidelines/examples

[ashishsingh18]

Hi VolView Team,

First of all, thank you for the amazing tool you've developed — it's an impressive platform for visualization and interaction, and I truly appreciate the effort that has gone into making it accessible and extensible.

We are interested in developing plugins for VolView and I was wondering if you have any official guidelines, examples, or templates that could help get started.

It would be great if you could point me to:

-Any recommended structure or API for plugins.

-Example plugins or starter templates (if available).

-Best practices for integrating custom tools or workflows into VolView.

Thanks in advance for your guidance, and once again, thank you for making such a powerful tool available to the community!

Best Regards,
Ashish

[PaulHax]

Hello! Your very kind.

Instead of simply forking/branching, this repo takes a file override approach to customizing VolView:
https://github.com/KitwareMedical/VolViewCustomAppTemplate

@floryst and @jadh4v have more experence using VolViewCustomAppTemplate.

There is some work sending images back and forth from a Python server in the server directory of VolView repo proper. That code has not been mantained lately though.

What kind of plugins/modifications are you interested in? Processing images or integrations with PACS backends, etc...

[ashishsingh18]

Thank you @PaulHax for the quick and helpful response!

We’ve been exploring the VolViewCustomAppTemplate, but are currently running into issues getting it to work. My colleague @TomTonroe has also tried it, but without success so far.

If you could point us to a few key examples, using the override approach and the custom app template, especially around the following, it would be incredibly helpful:

• Modifying or extending the UI (e.g., adding custom panels, tools, buttons, labels, etc.)
• Integrating new algorithms (e.g., ITK-based image processing or custom logic)
• Adding new rendering capabilities or customizing existing visualizations

We are trying to use VolView for internal research projects. I’ve previously worked with Kitware tools like ITK, VTK, and the older desktop version of VolView, and I’m excited about the potential of the new web version of VolView as a lightweight and flexible frontend for image analysis workflows.
We'd really appreciate any additional guidance or examples you can point us to, so we can get started.

Thanks again!

Best Regards,
Ashish

[PaulHax]

Sounds like some interesting work.

The one public example we have using the VolViewCustomAppTemplate is here:
https://github.com/kitwaremedical/lungair-web-application

But there are some other things in the pipe from @arhowe00

Regarding new image processing algos, the "paint" tool has 2 different segmentation "Processes." One of them uses itk-wasm to pull in C++ ITK filters.

Regarding rendering, we don't deveate to much from vtk.js's built -in rendering. But I think it would be straightforward to copy the current 2D or 3D views and modify them.

If you would like to discuss further on a call how we can work together, happy to jump on a call with you:

paul.elliott@kitware.com

[arhowe00]

I'll work on writing up a guide based on my experience with some of our offshoot work.

[arhowe00]

How to make a VolView Custom App

Overview

VolView does not have a formal custom app framework, and it does not have explicit modularity that can host an ecosystem of independent apps or modules. Creating a custom VolView app is forking the upstream repository at a fixed commit hash and then editing the files to add new modules, such as an EHR viewer or AI chatbot. There is a useful repository that expedites the process of including the core VolView app into a submodule and then copying both VolView's files and your own files into the build tree via an override system, where the overrides take precedent over core VolView files and you can reference core VolView files as if they were in your own source tree.

Way 1: Using the Custom App Template

Currently, the template (the version as of this document, e73373) does not build, so you will have to do extra work in fixing the template. If you are able to get the custom app template to build, please make a contribution to the template repo. After using the template, start overwriting new files and import core VolView modules with @ to reference the root directory of core VolView. This method works with 2 trees, and you are generally not supposed to edit the core VolView tree – instead, overwrite the files in the root of the custom app template repo. The core VolView tree is a git submodule in core/VolView.

Way 2: Fork VolView

This is the most straightforward method that will work out of the box. Instead of doing overrides, fork VolView and modify the app to fit your needs.

Way 3: Fork something that uses the Custom App Template

Due to the lack of function in the Custom App Template, it may not be unreasonable to fork a repository that successfully used the Custom App Template (as it debugged away the issues with the cookie cutter). Things would work exactly as expected according to the Custom App Template. However, it still may be more worthwhile just to fork VolView.

Common Actions

1. You can add "modules" (tabs) by editing the file src/components/ModulePanel.vue. First, you make a Vue component in a file (such as src/components/AnalyticsModule.vue) specifying what you want in the module, usually some logic that modifies app state in a way that it is seen in the viewer, and then you import the component into ModulePanel.vue and insert it as one of the tabs.

2. If you want to show custom information in the viewer, such as below, these are written as separate Vue Components. You write the Vue component, which is an atomic file containing the <script>, <template>, and <style> combination (see any .vue file for reference). Once you write the components (see below for 2 separate component examples, which are combined with a custom core volview component), you import it in src/components/LayoutGrid.vue to expose it to the layout "generator" (the thing that inserts all the components in, e.g. the parent grid hosting the 3 components below). Then, in src/config.ts, you define the layout that actually uses the components (i.e. the placement of the child components). You can see examples of creating the view ids. You can see how the layouts are defined. You can make your own layouts with their own name or you can edit the existing layouts.

Pitfalls

1. Don't override too many files. As this is not an independent app ecosystem, overriding upstream VolView files may be necessary, such as for adding a new view or a chatbot module. However, wherever possible, add new functionality in separate files instead of via overrides, and communicate with core VolView JS/TS/Vue files via the most high-level API possible. This is because if you wish to update the core VolView version of your custom app, you will have to resolve merge conflicts between your overrides and the upstream VolView, and you may not know why things changed with the file you overrided and how to modify your override decisions to continue working after the core VolView version changes. The lower level your changes, the more work that is. The more overrides you made to variables, functions, etc., the more work that is.
2. I could only think of one major pitfall.

Examples

1. The LungAIR web app, which uses the custom app template.
2. The VolView Insight web app, which uses the custom app template. There are more features than in the LungAIR web app.

[arhowe00]

How to make a VolView Custom App

Overview

VolView does not have a formal custom app framework, and it does not have explicit modularity that can host an ecosystem of independent apps or modules. Creating a custom VolView app is forking the upstream repository at a fixed commit hash and then editing the files to add new modules, such as an EHR viewer or AI chatbot. There is a useful repository that expedites the process of including the core VolView app into a submodule and then copying both VolView's files and your own files into the build tree via an override system, where the overrides take precedent over core VolView files and you can reference core VolView files as if they were in your own source tree.

Way 1: Using the Custom App Template

Currently, the template (the version as of this document, e73373) does not build, so you will have to do extra work in fixing the template. If you are able to get the custom app template to build, please make a contribution to the template repo. After using the template, start overwriting new files and import core VolView modules with @ to reference the root directory of core VolView. This method works with 2 trees, and you are generally not supposed to edit the core VolView tree – instead, overwrite the files in the root of the custom app template repo. The core VolView tree is a git submodule in core/VolView.

Way 2: Fork VolView

This is the most straightforward method that will work out of the box. Instead of doing overrides, fork VolView and modify the app to fit your needs.

Way 3: Fork something that uses the Custom App Template

Due to the lack of function in the Custom App Template, it may not be unreasonable to fork a repository that successfully used the Custom App Template (as it debugged away the issues with the cookie cutter). Things would work exactly as expected according to the Custom App Template. However, it still may be more worthwhile just to fork VolView.

Common Actions

1. You can add "modules" (tabs) by editing the file src/components/ModulePanel.vue. First, you make a Vue component in a file (such as src/components/AnalyticsModule.vue) specifying what you want in the module, usually some logic that modifies app state in a way that it is seen in the viewer, and then you import the component into ModulePanel.vue and insert it as one of the tabs.

2. If you want to show custom information in the viewer, such as below, these are written as separate Vue Components. You write the Vue component, which is an atomic file containing the <script>, <template>, and <style> combination (see any .vue file for reference). Once you write the components (see below for 2 separate component examples, which are combined with a custom core volview component), you import it in src/components/LayoutGrid.vue to expose it to the layout "generator" (the thing that inserts all the components in, e.g. the parent grid hosting the 3 components below). Then, in src/config.ts, you define the layout that actually uses the components (i.e. the placement of the child components). You can see examples of creating the view ids. You can see how the layouts are defined. You can make your own layouts with their own name or you can edit the existing layouts.

Pitfalls

1. Don't override too many files. As this is not an independent app ecosystem, overriding upstream VolView files may be necessary, such as for adding a new view or a chatbot module. However, wherever possible, add new functionality in separate files instead of via overrides, and communicate with core VolView JS/TS/Vue files via the most high-level API possible. This is because if you wish to update the core VolView version of your custom app, you will have to resolve merge conflicts between your overrides and the upstream VolView, and you may not know why things changed with the file you overrided and how to modify your override decisions to continue working after the core VolView version changes. The lower level your changes, the more work that is. The more overrides you made to variables, functions, etc., the more work that is.
2. I could only think of one major pitfall.

Examples

1. The LungAIR web app, which uses the custom app template.
2. The VolView Insight web app, which uses the custom app template. There are more features than in the LungAIR web app.