Add standardized client preprocessing capabilities by bourdaisj · Pull Request #52 · Kitware/trame-client

bourdaisj · 2026-03-19T17:00:30Z

This PR adds a widget to the client that aims to allow library consumers to register and run JS modules files with minimal boilerplate on the client side.

This PR is currently a draft.

Things that I am planning to do before marking as ready:

finalize examples
write documentatio + usage guide
write tests

EDIT:

add UMD based VTK.js example instead of wasm - STL reader setRemoveDuplicateVertices look good
get rid of pnpm lock file in the example
take a look at why the tests are failing

EDIT:

figure out a satisfying public API
figure out the .value reactive vs ref stuff

bourdaisj · 2026-03-19T17:00:49Z

FYI @finetjul @finetjul @luciemac

bourdaisj · 2026-04-02T17:59:41Z

@jourdain @psavery Can you take a look at why the CI is failing? I don't have the beginning of an idea

jourdain · 2026-04-07T00:22:47Z

I think the issue is because the vue2 client is not built.
=> At least it was my issue locally.

jourdain · 2026-04-07T00:31:37Z

.../trame_client/module/user_preprocessors_module_scripts' does not exist

You may need to pre-create the directory.

bourdaisj · 2026-04-10T14:19:39Z

I'm confused... the folder is here, it is in the wheel, it is packaged, it has a init.py in it. so why would it missing? Thx for the tip anyway, i'll continue investigating

bourdaisj · 2026-04-10T14:25:12Z

well turns out the init.py was gitignored, feeling dumb right now. CI is now green! I'll finalize this and mark as ready

This new PreProcessor widget aims to allow library consumers to register JS module files with minimal boilerplate, and later call functions defined in those registered modules at runtime inside the trame client

previously, only ES module were supported. Library consumer can now pass .umd.js files

jourdain · 2026-04-10T16:00:55Z

I'll try to do a final review this weekend so we can merge it sometime next week.

bourdaisj · 2026-04-10T16:03:43Z

I still need to iron out the public API, write some docstring for the readthedocs, and figure out how I can test this effectively, but that should not take too long. i'll tag you once done.

bourdaisj · 2026-04-13T12:12:27Z

@jourdain I pushed something that aim to keep the API simple and usable while decoupling from the widget module. wdyt?

jourdain · 2026-04-17T17:11:31Z

+from trame.ui.vuetify3 import SinglePageLayout
+
+from trame.widgets import client, vuetify3, html
+from trame_client.preprocessor import register_preprocessing_script


Any way for not importing things from trame_client.*? Can we just do something like

from trame.widgets import client, vuetify3, html client.register_external_script( name="validate_dicom_patient_name", script_file_path=DICOM_UTILS_SCRIPT, function_names=["validateDicomFilePatientName"], )

It could be nice if we could use that same method to point to standalone JS file too that do not need method/function to be called.

I did not want to pollute the widget file with too many dependencies, but yes - I think a good workaround is too keep all public API in trame.widgets.client. make sense to me

jourdain · 2026-04-17T17:13:38Z

+                vuetify3.VRow(),
+                vuetify3.VCol(cols=3),
+                # 3. Instantiate the PreProcessor widget
+                client.PreProcessor(


What about ?

client.Handler( mode="pre-processing", # <= I don't know that we need that, but I'm thinking out loud for some genericity function="validate_dicom_patient_name", input=..., completed=.... )

Handler might be good - yet, I'm not keen of one-word components/widgets.
what about: ScriptHandler, ScriptDispatcher.
what would be some other values of mode param?

I don't actually know if we have different behavior/value for that property. So if you don't think of any, no need to add it.

I still prefer Handler than ScriptHandler. The reason is that it is a client Handler, but I don't see the point of saying client.ClientHandler

jourdain · 2026-04-17T17:17:35Z

+                        self.preprocessing_pipeline_completed,
+                        "[$event.type, $event.outputs]",
+                    ),
+                ) as patient_name_preprocessor,


... as client_handler:

jourdain · 2026-04-17T17:18:12Z

+        # Mark your state as client_only!
+        self.state.client_only("dicom_file_set")
+
+        register_preprocessing_script(


client.register_external_script(...

jourdain · 2026-04-17T17:18:32Z

+                        persistent_hint=True,
+                    )
+
+                    with client.PreProcessor(


client.Handler(...

jourdain · 2026-04-17T17:18:54Z

+                        failure=(self.handle_nifti_convertion_error, "[$event]"),
+                        # error event for any exception raised during logic execution
+                        error=(self.handle_nifti_convertion_error, "[$event]"),
+                    ) as preprocessing:


as client_handler:

jourdain · 2026-04-17T17:19:49Z

+        # Mark your state as client_only!
+        self.state.client_only("dicom_file_set")
+
+        self.dicom_utils_preprocessor = register_preprocessing_script(


client.register_external_script(...

jourdain · 2026-04-17T17:20:05Z

+                vuetify3.VContainer(fluid=True),
+                vuetify3.VRow(),
+                vuetify3.VCol(cols=3),
+                client.PreProcessor(


client.Handler(

jourdain · 2026-04-17T17:20:25Z

+                        "[$event.type, $event.outputs]",
+                    ),
+                ),
+                client.PreProcessor(


client.Handler

jourdain · 2026-04-17T17:27:01Z

+    def __init__(self, server=None):
+        super().__init__(server)
+
+        self.read_dicom_tags_preprocessor_logic = register_preprocessing_script(


client.register_external_script

jourdain · 2026-04-17T17:28:37Z

+        self.state.decimation_factor = 5
+        self.state.hole_size = 1000.0
+
+        register_preprocessing_script(


client.register_external_script

jourdain · 2026-04-17T17:28:57Z

+            self.ui.title.set_text("Client Preprocessing UMD Modules")
+
+            with self.ui.toolbar:
+                with client.PreProcessor(


client.Handler

jourdain · 2026-04-17T17:30:37Z

@@ -0,0 +1,3 @@
+*
+!__init__.py


Do you need the init.py in that directory?

Yes, it is needed so that it ends up being packaged into the wheel

No, you can be explicit that the directory contains non py file. That is inside the pyproject.toml that you have to specify that.

jourdain · 2026-04-17T17:33:57Z

+
+def get_user_preprocessor_serve_url_prefix() -> Path:
+    return Path("__trame_client_preprocessors")
+


All those Path() should be const rather than methods.

I get your comment, but I don't like things that can get modified from the outside - or is there some kind of "real" const in python?

No but if you don't expose them, they are only available in that module and therefore not editable.

__all__ = ["setup"]

jourdain · 2026-04-17T17:34:58Z

+
+    server.enable_module(
+        {
+            "serve": {root_path.as_posix(): str(serve_path)},


Include version to prevent conflicting client version capability?

Let side could be { "serve: f"/__trame_client_handlers_{__version__}" : ... }

from trame_client import __version__

definitely. Looking at this, I'm also thinking the user script should be versioned/namespaced in some way so that they are cache friendly. probably a hash of the file would do the trick

We have some logic doing that kind of stuff here: https://github.com/Kitware/trame-client/blob/master/trame_client/utils/web_module.py

jourdain · 2026-04-17T17:37:37Z

+    "get_user_preprocessor_scripts_path",
+    "get_user_preprocessor_es_scripts_path",
+    "get_user_preprocessor_umd_scripts_path",
+    "get_user_preprocessor_serve_url_prefix",


Do we need those to be exposed?

I think the server needs to see setup

jourdain · 2026-04-17T17:38:00Z

    "DeepReactive",
    "LifeCycleMonitor",
    "SizeObserver",
+    "PreProcessor",


jourdain · 2026-04-17T17:39:03Z

@@ -0,0 +1,127 @@
+from pathlib import Path


name the file external_script_handler.py ?

user_provided_script_handler? or consumer_provided_script_handler?

I technically don't care for that file name (as it is not public), so you can be as explicit as you want. I just don't like preprocessor.py

jourdain · 2026-04-17T21:10:24Z

I like all your changes, I think we are getting really close. I guess I just want to get rid of the "preprocess*" properties and make them more generic.

bourdaisj requested a review from jourdain March 19, 2026 17:00

bourdaisj force-pushed the add-standardized-client-preprocessing-capabilities branch from b6f44be to 5d422ba Compare March 19, 2026 17:04

jourdain reviewed Mar 20, 2026

View reviewed changes

Comment thread trame_client/module/__init__.py

jourdain reviewed Mar 20, 2026

View reviewed changes

Comment thread vue3-app/src/preprocessor/loader.js Outdated

jourdain reviewed Mar 20, 2026

View reviewed changes

Comment thread vue3-app/src/preprocessor/loader.js Outdated

jourdain reviewed Mar 20, 2026

View reviewed changes

Comment thread examples/preprocessor/01_start_here.py Outdated

bourdaisj force-pushed the add-standardized-client-preprocessing-capabilities branch from 520fe14 to d3293d6 Compare March 24, 2026 16:25

jourdain reviewed Mar 26, 2026

View reviewed changes

Comment thread examples/preprocessor/04_preprocess_using_remote_es_module.py

jourdain reviewed Mar 26, 2026

View reviewed changes

Comment thread examples/preprocessor/03_nested_preprocessing_pipeline.py Outdated

bourdaisj commented Mar 26, 2026

View reviewed changes

Comment thread trame_client/widgets/trame.py Outdated

bourdaisj force-pushed the add-standardized-client-preprocessing-capabilities branch from 169750e to 71e5673 Compare March 27, 2026 12:24

bourdaisj self-assigned this Apr 2, 2026

bourdaisj force-pushed the add-standardized-client-preprocessing-capabilities branch 5 times, most recently from 603ff7c to 910dd80 Compare April 2, 2026 17:20

bourdaisj added 3 commits April 10, 2026 17:49

feat(PreProcessor): add a client preprocessing dispatcher widget

80416ea

This new PreProcessor widget aims to allow library consumers to register JS module files with minimal boilerplate, and later call functions defined in those registered modules at runtime inside the trame client

doc(PreProcessor): add note about usage with default docker bundle

eb80445

feat(PreProcessor): support UMD module registration

389b33b

previously, only ES module were supported. Library consumer can now pass .umd.js files

bourdaisj force-pushed the add-standardized-client-preprocessing-capabilities branch from 5fab55d to 9fd5195 Compare April 10, 2026 15:51

bourdaisj added 2 commits April 10, 2026 17:56

doc(PreProcessor): add usage examples

4644bb9

ci(tests): update python version

31cbe9d

bourdaisj force-pushed the add-standardized-client-preprocessing-capabilities branch from 9fd5195 to 31cbe9d Compare April 10, 2026 15:56

bourdaisj force-pushed the add-standardized-client-preprocessing-capabilities branch from 661fac1 to 98b18db Compare April 13, 2026 09:39

jourdain reviewed Apr 17, 2026

View reviewed changes

WIP: rework public API

0ed2f55

bourdaisj force-pushed the add-standardized-client-preprocessing-capabilities branch from 98b18db to 0ed2f55 Compare April 17, 2026 19:14


		def get_user_preprocessor_serve_url_prefix() -> Path:
		return Path("__trame_client_preprocessors")

Conversation

bourdaisj commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bourdaisj commented Mar 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bourdaisj commented Apr 2, 2026

Uh oh!

jourdain commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jourdain commented Apr 7, 2026

Uh oh!

bourdaisj commented Apr 10, 2026

Uh oh!

bourdaisj commented Apr 10, 2026

Uh oh!

jourdain commented Apr 10, 2026

Uh oh!

bourdaisj commented Apr 10, 2026

Uh oh!

bourdaisj commented Apr 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jourdain Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bourdaisj commented Mar 19, 2026 •

edited

Loading

jourdain commented Apr 7, 2026 •

edited

Loading

jourdain Apr 17, 2026 •

edited

Loading