pysnt.converters package#

SNT object converters for PySNT.

This module provides custom converters that transform SNT Java objects into Python equivalents (matplotlib figures, xarray datasets, etc.) and handles their display and visualization.

The converters module is organized into the following submodules: - core: Base utilities, constants, and factory functions - extractors: Graph vertex and edge attribute extraction (SNTGraph) - graph_converters: SNTGraph to NetworkX conversion - chart_converters: SNTChart to matplotlib conversion - structured_data_converters: SNTTable/Path/ImagePlus to xarray conversion and metadata extraction - display: Display and visualization functions - enhancement: Java object enhancement functionality

display(obj: Any, show: bool = True, **kwargs) → Any[source]#

Display any supported object type in the most appropriate way.

Handles Java objects, SNT objects, matplotlib figures, xarray objects, Viewer2D/3D objects, and lists. Automatically converts Java objects and creates multi-panel displays for lists.

Parameters:

obj (Any) – Object to display (Java objects, SNTObjects, matplotlib figures, xarray objects, Viewer2D/3D objects, lists, etc.)
show (bool, default True) – Whether to display the figure immediately. If False, creates the figure but doesn’t show it (useful for chaining: fig1 = pysnt.display(obj, show=False))
**kwargs – Display arguments including: - cmap: str, colormap for grayscale images - title: str, display title - figsize: tuple, figure size - orthoview: bool, for 3D viewers - panel_layout: str, layout for multi-panel displays - max_panels: int, maximum panels to display - origin: str, origin for image display (‘upper’, ‘lower’, ‘auto’)

Returns:

Return value depends on input type

Return type:

Any

register_snt_converters()[source]#

Register SNT converters with scyjava.

This function registers custom converters that transform SNT Java objects into Python equivalents. The converters handle: - SNT tables -> xarray datasets - SNT charts -> matplotlib figures - SNT graphs -> NetworkX graphs

Returns:: True if registration succeeded, False otherwise
Return type:: bool

list_converters() → List[Dict[str, Any]][source]#

List all registered SNT converters.

Returns:: List of converter information dictionaries containing: - name: converter name - predicate: predicate function name - converter: converter function name
Return type:: List[Dict[str, Any]]

enhance_java_object(obj: Any) → Any[source]#

Enhance a Java object with fallback show() and setVisible() methods if applicable.

This function checks if the object is an SNT chart or GUI object and if so, wraps it with an enhanced version that falls back to display() on GUI method failures.

Parameters:: obj (Any) – Java object to potentially enhance
Returns:: Enhanced wrapper object if applicable, otherwise the original object
Return type:: Any

Examples

>>> # For charts
>>> chart = stats.getHistogram('Branch length')
>>> enhanced_chart = enhance_java_object(chart)
>>> enhanced_chart.show()  # Will fallback to display() if GUI fails

>>> # For GUI objects
>>> ui = pysnt.PathManagerUI()
>>> enhanced_ui = enhance_java_object(ui)
>>> enhanced_ui.setVisible(True)  # Will fallback to display() if GUI fails

auto_enhance_java_objects(enabled: bool = True)[source]#

Enable or disable automatic enhancement of Java objects.

When enabled, this function monkey-patches scyjava’s jimport to automatically enhance returned Java objects with fallback show() methods.

Parameters:: enabled (bool, default True) – Whether to enable automatic enhancement

Note

This is experimental and may have side effects. Use with caution.

register_display_handler(obj_type: str, handler_func)[source]#

Register a custom display handler for a specific SNT object type.

This function allows users to register custom display handlers for specific SNT object types. When an object of the registered type is displayed, the custom handler will be called instead of the default display logic.

Parameters:

obj_type (str) – The SNT object type identifier (e.g., ‘SNT_Tree’, ‘SNT_Path’)
handler_func (Callable[[Dict[str, Any]], None]) – Function that takes an SNTObject dictionary and displays it

Examples

>>> def display_my_object(snt_dict):
...     print(f"My object: {snt_dict.get('name')}")
>>>
>>> register_display_handler('SNT_MyObject', display_my_object)

class SNTObject[source]#

Bases: TypedDict

A structured container for SNT converted objects.

This TypedDict defines the structure for python converted objects that encapsulate converted data along with its type information, metadata, and potential convertion error state.

type#

The Python type of the data being stored.

Type:: Type

data#

The actual converted data.

Type:: Any

metadata#

A dictionary containing additional information about the converted object (e.g., source identifiers or processing flags).

Type:: Dict[str, Any]

error#

An exception object if an error occurred during object convertion (which typically means data is None), None otherwise.

Type:: Exception | None

type: Type#

data: Any#

metadata: Dict[str, Any]#

error: Exception | None#

tree_to_points(tree)[source]#

Extract node coordinates from a Tree as a numpy array.

This is a convenience function that extracts the numpy array directly. Tree objects are also automatically converted when using pysnt.to_python(), which returns the same numpy array.

Parameters:: tree (Tree) – PySNT Tree object
Returns:: Array of shape (N, 3) containing XYZ coordinates
Return type:: np.ndarray

Examples

>>> from pysnt.converters.tree_converters import tree_to_points
>>> points = tree_to_points(tree)
>>> print(points.shape)  # (N, 3)

>>> # Automatic conversion via pysnt.to_python() returns the same array:
>>> points = pysnt.to_python(tree)  # Same numpy array result
>>> print(points.shape)  # (N, 3)

Notes

The difference between this function and pysnt.to_python(tree): - tree_to_points(tree): Returns numpy array directly - pysnt.to_python(tree): Also returns numpy array (via registered converter) - _convert_tree_to_points(tree): Returns SNTObject dict (internal use only)

pysnt.converters package#

Submodules#