Compose a series of monotonic piecewise functions and a color transfer function into a single color transfer function

[jadh4v]

Context

Imaging applications may require multiple scalar transforms on pixel data before it is rendered. These transforms can be done directly on the image pixel array before passing the image to the GPU. However, the transform can necessitate a data type conversion to higher number of bytes to maintain precision. This can consume a lot of memory and make pixel arrays very large if the application is handling many such images simultaneously.

We implement a feature to compose multiple scalar transforms (piecewise functions) and one color transfer function into a single color transfer function that represents the entire transform from original input scalars to output display colors. This allows the transforms to be applied on the GPU via the composed transfer function's lookup at render time, rather than storing the transformed pixel arrays inflated on the CPU side.

Results

We have added an example that shows how three different scalar transforms (e.g. modality transforms, values-of-interest, color-window adjustments, etc) can be composed along with a color function.

Changes

• vtkPiecewiseFunction.findX(y) (new method): inverse of getValue(). Locates the first segment whose endpoint values bracket y and bisects it through forward evaluation, so midpoint and sharpness are honored. Returns null when no x maps to y (e.g. out-of-range values with clamping off).

• compose(fnList, colorFn, outputFn, errorThreshold?, maxSubdivisionDepth?) (new helper in Common/DataModel/PiecewiseFunction/helpers): composes an ordered chain of piecewise value-transform functions with a final-stage color transfer function into a single output color transfer function. Breakpoints from every stage are pulled back through the upstream inverses (findX) into the source domain, then forward-propagated to sample the composed color at each one.

  • Transform functions must be monotonic (getType() !== 'Varied') so breakpoints can be pulled back unambiguously. Without an errorThreshold they must also be piecewise linear (midpoint 0.5, sharpness 0 on every segment), since the output interpolates linearly between the collected breakpoints; with an errorThreshold, shaped (non-linear) segments in any stage are captured instead by recursively subdividing each output segment at its midpoint until linear interpolation matches the true composed color to within the threshold on every color channel. The subdivision is depth-first, so the threshold alone cannot bound the node count: maxSubdivisionDepth (default 24) caps the worst case at 2^depth − 1 extra nodes per segment and guarantees termination at discontinuities. The color transfer function itself is never restricted.
  • Returns the maximum measured midpoint deviation between the composed output and the true composed chain (0 means exact; a value above errorThreshold means the depth cap stopped refinement somewhere), or null when an input is rejected (with a warning, leaving outputFn untouched). Note that 0 is falsy: test the result against null for success, never its truthiness.
  • Usage: compose([modalityFn, voiFn, userFn], colorFn, resultFn, 0.01) — see the new example.

• vtkColorTransferFunction.getDataPointer() (new method): returns the function's nodes, for parity with the VTK/C++ API.

• vtkPiecewiseFunction typings fixed: getNodeValue/setNodeValue were declared to return void but return -1 (index out of range) or 1 (success); val narrowed from any[] to number[].

• New example Rendering/ComposePiecewiseFunctions: DICOM slice viewer chaining modality, VOI, and interactive window/level transforms with a color map preset into a single transfer function.

• Documentation and TypeScript definitions were updated to match those changes

PR and Code Checklist

• semantic-release commit messages
• Run npm run reformat to have correctly formatted code

Testing

• This change adds or fixes unit tests
• Tested environment:
  • vtk.js: latest master
  • OS: macOS 26.5.1 (25F80) Tahoe
  • Browser: Chrome Version 149.0.7827.55 (Official Build) (arm64)

[finetjul]

Did you check ColorTransferFunction/CssFilters.js ? Maybe it already does what you need...

[jadh4v]

@finetjul Is it ok to return a direct reference to model.nodes or should we make a copy of the array?

[finetjul]

In VTK.JS world, it can be ok (just for performance reasons), but it is done with 2 separate methods: the default one returns a copy and another method with the same name but suffixed with "ByReference" returns a direct reference. (maybe add a warning in the documentation to not modify the array). You can look at the getArray function in macros.js

[jadh4v]

Did you check ColorTransferFunction/CssFilters.js ? Maybe it already does what you need...

Interesting. These filters look like direct color transforms (i.e. transforming 5d color vectors [R, G,B, A, 1] whereas we are working mostly with scalar value functions/transforms that are not restricted to linear matrix transforms. If I understand correctly the CssFilters transforms are entirely represented using 5D matrices or a composition of them.

[finetjul]

Did you check ColorTransferFunction/CssFilters.js ? Maybe it already does what you need...

Interesting. These filters look like direct color transforms (i.e. transforming 5d color vectors [R, G,B, A, 1] whereas we are working mostly with scalar value functions/transforms that are not restricted to linear matrix transforms. If I understand correctly the CssFilters transforms are entirely represented using 5D matrices or a composition of them.

Indeed, what you want to do is non-linear. Those 5D matrices won't work for your use case. Nevermind

[finetjul]

@jadh4v please let us know when it is a good time for us to do a code review.

[jadh4v]

@jadh4v please let us know when it is a good time for us to do a code review.

@finetjul @sankhesh The PR is ready for re-review. I have made some significant changes to my previous approach. Primarily taking an iterative numerical approach for computing inverse as well as additional bisection of composed function.

[sankhesh]

Should there be another stop condition (like an epsilon) for near-flat slopes?