spateo.plotting.static.three_d_plot.three_dims_plots#

Module Contents#

Functions#

wrap_to_plotter(plotter, model[, key, background, ...])

What needs to be added to the visualization window.

three_d_plot(model[, key, filename, jupyter, ...])

Visualize reconstructed 3D model.

three_d_multi_plot(model[, key, filename, jupyter, ...])

Multi-view visualization of reconstructed 3D model.

three_d_animate(models[, stable_model, stable_kwargs, ...])

Animated visualization of 3D reconstruction model.

merge_animations([mp4_files, mp4_folder, filename])

Use MoviePy to compose a new animation and play multiple animations together in the new animation.
spateo.plotting.static.three_d_plot.three_dims_plots.wrap_to_plotter(plotter: pyvista.Plotter, model: Union[pyvista.PolyData, pyvista.UnstructuredGrid, pyvista.MultiBlock], key: Union[str, list] = None, background: str = 'white', cpo: Union[str, list] = 'iso', colormap: Optional[Union[str, list]] = None, ambient: Union[float, list] = 0.2, opacity: Union[float, numpy.ndarray, list] = 1.0, model_style: Union[Literal[points, surface, wireframe], list] = 'surface', model_size: Union[float, list] = 3.0, show_legend: bool = True, legend_kwargs: Optional[dict] = None, show_outline: bool = False, outline_kwargs: Optional[dict] = None, text: Optional[str] = None, text_kwargs: Optional[dict] = None)[source]#

What needs to be added to the visualization window.

Parameters
plotter

The plotting object to display pyvista/vtk model.

model

A reconstructed model.

key

The key under which are the labels.

background

The background color of the window.

cpo

Camera position of the active render window. Available cpo are:

  • Iterable containing position, focal_point, and view up.

    E.g.: [(2.0, 5.0, 13.0), (0.0, 0.0, 0.0), (-0.7, -0.5, 0.3)].

  • Iterable containing a view vector.

    E.g.: [-1.0, 2.0, -5.0].

  • A string containing the plane orthogonal to the view direction.

    E.g.: 'xy', 'xz', 'yz', 'yx', 'zx', 'zy', 'iso'.

colormap

Name of the Matplotlib colormap to use when mapping the scalars.

When the colormap is None, use {key}_rgba to map the scalars, otherwise use the colormap to map scalars.

ambient

When lighting is enabled, this is the amount of light in the range of 0 to 1 (default 0.0) that reaches the actor when not directed at the light source emitted from the viewer.

opacity

Opacity of the model.

If a single float value is given, it will be the global opacity of the model and uniformly applied everywhere, elif a numpy.ndarray with single float values is given, it will be the opacity of each point. - should be between 0 and 1.

A string can also be specified to map the scalars range to a predefined opacity transfer function (options include: ‘linear’, ‘linear_r’, ‘geom’, ‘geom_r’).

model_style

Visualization style of the model. One of the following:

  • model_style = 'surface',

  • model_style = 'wireframe',

  • model_style = 'points'.

model_size

If model_style = 'points', point size of any nodes in the dataset plotted.

If model_style = 'wireframe', thickness of lines.

show_legend

whether to add a legend to the plotter.

legend_kwargs

A dictionary that will be pass to the add_legend function. By default, it is an empty dictionary and the add_legend function will use the {"legend_size": None, "legend_loc": None, "legend_size": None, "legend_loc": None, "title_font_size": None, "label_font_size": None, "font_family": "arial", "fmt": "%.2e", "n_labels": 5, "vertical": True} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

show_outline

whether to produce an outline of the full extent for the model.

outline_kwargs

A dictionary that will be pass to the add_outline function.

By default, it is an empty dictionary and the add_legend function will use the {"outline_width": 5.0, "outline_color": "black", "show_labels": True, "font_size": 16, "font_color": "white", "font_family": "arial"} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

text

The text to add the rendering.

text_kwargs

A dictionary that will be pass to the add_text function.

By default, it is an empty dictionary and the add_legend function will use the { "font_family": "arial", "font_size": 12, "font_color": "black", "text_loc": "upper_left"} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

spateo.plotting.static.three_d_plot.three_dims_plots.three_d_plot(model: Union[pyvista.PolyData, pyvista.UnstructuredGrid, pyvista.MultiBlock], key: Union[str, list] = None, filename: Optional[str] = None, jupyter: Union[bool, Literal[panel, none, pythreejs, static, ipygany]] = False, off_screen: bool = False, window_size: tuple = (512, 512), background: str = 'white', cpo: Union[str, list] = 'iso', colormap: Optional[Union[str, list]] = None, ambient: Union[float, list] = 0.2, opacity: Union[float, numpy.ndarray, list] = 1.0, model_style: Union[Literal[points, surface, wireframe], list] = 'surface', model_size: Union[float, list] = 3.0, show_legend: bool = True, legend_kwargs: Optional[dict] = None, show_outline: bool = False, outline_kwargs: Optional[dict] = None, text: Optional[str] = None, text_kwargs: Optional[dict] = None, view_up: tuple = (0.5, 0.5, 1), framerate: int = 24, plotter_filename: Optional[str] = None)[source]#

Visualize reconstructed 3D model.

Parameters
model

A reconstructed model.

key

The key under which are the labels.

filename

Filename of output file. Writer type is inferred from the extension of the filename.

  • Output an image file,please enter a filename ending with '.png', '.tif', '.tiff', '.bmp', '.jpeg', '.jpg', '.svg', '.eps', '.ps', '.pdf', '.tex'.

  • Output a gif file, please enter a filename ending with .gif.

  • Output a mp4 file, please enter a filename ending with .mp4.

jupyter

Whether to plot in jupyter notebook. Available jupyter are:

  • 'none' - Do not display in the notebook.

  • 'pythreejs' - Show a pythreejs widget

  • 'static' - Display a static figure.

  • 'ipygany' - Show an ipygany widget

  • 'panel' - Show a panel widget.

off_screen

Renders off-screen when True. Useful for automated screenshots.

window_size

Window size in pixels. The default window_size is [512, 512].

background

The background color of the window.

cpo

Camera position of the active render window. Available cpo are:

  • Iterable containing position, focal_point, and view up.

    E.g.: [(2.0, 5.0, 13.0), (0.0, 0.0, 0.0), (-0.7, -0.5, 0.3)].

  • Iterable containing a view vector.

    E.g.: [-1.0, 2.0, -5.0].

  • A string containing the plane orthogonal to the view direction.

    E.g.: 'xy', 'xz', 'yz', 'yx', 'zx', 'zy', 'iso'.

colormap

Name of the Matplotlib colormap to use when mapping the scalars.

When the colormap is None, use {key}_rgba to map the scalars, otherwise use the colormap to map scalars.

ambient

When lighting is enabled, this is the amount of light in the range of 0 to 1 (default 0.0) that reaches the actor when not directed at the light source emitted from the viewer.

opacity

Opacity of the model.

If a single float value is given, it will be the global opacity of the model and uniformly applied everywhere, elif a numpy.ndarray with single float values is given, it will be the opacity of each point. - should be between 0 and 1.

A string can also be specified to map the scalars range to a predefined opacity transfer function (options include: ‘linear’, ‘linear_r’, ‘geom’, ‘geom_r’).

model_style

Visualization style of the model. One of the following:

  • model_style = 'surface',

  • model_style = 'wireframe',

  • model_style = 'points'.

model_size

If model_style = 'points', point size of any nodes in the dataset plotted.

If model_style = 'wireframe', thickness of lines.

show_legend

whether to add a legend to the plotter.

legend_kwargs

A dictionary that will be pass to the add_legend function. By default, it is an empty dictionary and the add_legend function will use the {"legend_size": None, "legend_loc": None,  "legend_size": None, "legend_loc": None, "title_font_size": None, "label_font_size": None, "font_family": "arial", "fmt": "%.2e", "n_labels": 5, "vertical": True} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

show_outline

whether to produce an outline of the full extent for the model.

outline_kwargs

A dictionary that will be pass to the add_outline function.

By default, it is an empty dictionary and the add_legend function will use the {"outline_width": 5.0, "outline_color": "black", "show_labels": True, "font_size": 16, "font_color": "white", "font_family": "arial"} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

text

The text to add the rendering.

text_kwargs

A dictionary that will be pass to the add_text function.

By default, it is an empty dictionary and the add_legend function will use the { "font_family": "arial", "font_size": 12, "font_color": "black", "text_loc": "upper_left"} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

view_up

The normal to the orbital plane. Only available when filename ending with .mp4 or .gif.

framerate

Frames per second. Only available when filename ending with .mp4 or .gif.

plotter_filename

The filename of the file where the plotter is saved.

Writer type is inferred from the extension of the filename.

  • Output a gltf file, please enter a filename ending with .gltf.

  • Output a html file, please enter a filename ending with .html.

  • Output an obj file, please enter a filename ending with .obj.

  • Output a vtkjs file, please enter a filename without format.

Returns

List of camera position, focal point, and view up.

Returned only if filename is None or filename ending with '.png', '.tif', '.tiff', '.bmp', '.jpeg', '.jpg', '.svg', '.eps', '.ps', '.pdf', '.tex'.

img: Numpy array of the last image.

Returned only if filename is None or filename ending with '.png', '.tif', '.tiff', '.bmp', '.jpeg', '.jpg', '.svg', '.eps', '.ps', '.pdf', '.tex'.

Return type

cpo

spateo.plotting.static.three_d_plot.three_dims_plots.three_d_multi_plot(model: Union[pyvista.PolyData, pyvista.UnstructuredGrid, pyvista.MultiBlock], key: Union[str, list] = None, filename: Optional[str] = None, jupyter: Union[bool, Literal[panel, none, pythreejs, static, ipygany]] = False, off_screen: bool = False, shape: Union[str, list, tuple] = None, window_size: Optional[tuple] = None, background: str = 'white', cpo: Union[str, list] = 'iso', colormap: Optional[Union[str, list]] = None, ambient: Union[float, list] = 0.2, opacity: Union[float, numpy.ndarray, list] = 1.0, model_style: Union[Literal[points, surface, wireframe], list] = 'surface', model_size: Union[float, list] = 3.0, show_legend: bool = True, legend_kwargs: Optional[dict] = None, show_outline: bool = False, outline_kwargs: Optional[dict] = None, text: Union[str, list] = None, text_kwargs: Optional[dict] = None, view_up: tuple = (0.5, 0.5, 1), framerate: int = 24, plotter_filename: Optional[str] = None)[source]#

Multi-view visualization of reconstructed 3D model.

Parameters
model

A MultiBlock of reconstructed models or a reconstructed model.

key

The key under which are the labels.

filename

Filename of output file. Writer type is inferred from the extension of the filename.

  • Output an image file,please enter a filename ending with '.png', '.tif', '.tiff', '.bmp', '.jpeg', '.jpg', '.svg', '.eps', '.ps', '.pdf', '.tex'.

  • Output a gif file, please enter a filename ending with .gif.

  • Output a mp4 file, please enter a filename ending with .mp4.

jupyter

Whether to plot in jupyter notebook. Available jupyter are:

  • 'none' - Do not display in the notebook.

  • 'pythreejs' - Show a pythreejs widget

  • 'static' - Display a static figure.

  • 'ipygany' - Show an ipygany widget

  • 'panel' - Show a panel widget.

off_screen

Renders off-screen when True. Useful for automated screenshots.

shape

Number of sub-render windows inside the main window. By default, there is only one render window.

  • Specify two across with ``shape``=(2, 1) and a two by two grid with ``shape``=(2, 2).

  • shape Can also accept a string descriptor as shape.

    E.g.: shape="3|1" means 3 plots on the left and 1 on the right, E.g.: shape="4/2" means 4 plots on top and 2 at the bottom.

window_size

Window size in pixels. The default window_size is [512, 512].

background

The background color of the window.

cpo

Camera position of the active render window. Available cpo are:

  • Iterable containing position, focal_point, and view up.

    E.g.: [(2.0, 5.0, 13.0), (0.0, 0.0, 0.0), (-0.7, -0.5, 0.3)].

  • Iterable containing a view vector.

    E.g.: [-1.0, 2.0, -5.0].

  • A string containing the plane orthogonal to the view direction.

    E.g.: 'xy', 'xz', 'yz', 'yx', 'zx', 'zy', 'iso'.

colormap

Name of the Matplotlib colormap to use when mapping the scalars.

When the colormap is None, use {key}_rgba to map the scalars, otherwise use the colormap to map scalars.

ambient

When lighting is enabled, this is the amount of light in the range of 0 to 1 (default 0.0) that reaches the actor when not directed at the light source emitted from the viewer.

opacity

Opacity of the model.

If a single float value is given, it will be the global opacity of the model and uniformly applied everywhere, elif a numpy.ndarray with single float values is given, it will be the opacity of each point. - should be between 0 and 1.

A string can also be specified to map the scalars range to a predefined opacity transfer function (options include: ‘linear’, ‘linear_r’, ‘geom’, ‘geom_r’).

model_style

Visualization style of the model. One of the following:

  • model_style = 'surface',

  • model_style = 'wireframe',

  • model_style = 'points'.

model_size

If model_style = 'points', point size of any nodes in the dataset plotted.

If model_style = 'wireframe', thickness of lines.

show_legend

whether to add a legend to the plotter.

legend_kwargs

A dictionary that will be pass to the add_legend function. By default, it is an empty dictionary and the add_legend function will use the {"legend_size": None, "legend_loc": None,  "legend_size": None, "legend_loc": None, "title_font_size": None, "label_font_size": None, "font_family": "arial", "fmt": "%.2e", "n_labels": 5, "vertical": True} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

show_outline

whether to produce an outline of the full extent for the model.

outline_kwargs

A dictionary that will be pass to the add_outline function.

By default, it is an empty dictionary and the add_legend function will use the {"outline_width": 5.0, "outline_color": "black", "show_labels": True, "font_size": 16, "font_color": "white", "font_family": "arial"} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

text

The text to add the rendering.

text_kwargs

A dictionary that will be pass to the add_text function.

By default, it is an empty dictionary and the add_legend function will use the { "font_family": "arial", "font_size": 12, "font_color": "black", "text_loc": "upper_left"} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

view_up

The normal to the orbital plane. Only available when filename ending with .mp4 or .gif.

framerate

Frames per second. Only available when filename ending with .mp4 or .gif.

plotter_filename

The filename of the file where the plotter is saved.

Writer type is inferred from the extension of the filename.

  • Output a gltf file, please enter a filename ending with .gltf.

  • Output a html file, please enter a filename ending with .html.

  • Output an obj file, please enter a filename ending with .obj.

  • Output a vtkjs file, please enter a filename without format.

spateo.plotting.static.three_d_plot.three_dims_plots.three_d_animate(models: Union[List[PolyData or UnstructuredGrid], pyvista.MultiBlock], stable_model: Optional[Union[pyvista.PolyData, pyvista.UnstructuredGrid, pyvista.MultiBlock]] = None, stable_kwargs: Optional[dict] = None, key: Optional[str] = None, filename: str = 'animate.mp4', jupyter: Union[bool, Literal[panel, none, pythreejs, static, ipygany]] = False, off_screen: bool = False, window_size: tuple = (512, 512), background: str = 'white', cpo: Union[str, list] = 'iso', colormap: Optional[Union[str, list]] = None, ambient: Union[float, list] = 0.2, opacity: Union[float, numpy.ndarray, list] = 1.0, model_style: Union[Literal[points, surface, wireframe], list] = 'surface', model_size: Union[float, list] = 3.0, show_legend: bool = True, legend_kwargs: Optional[dict] = None, show_outline: bool = False, outline_kwargs: Optional[dict] = None, text: Optional[str] = None, text_kwargs: Optional[dict] = None, framerate: int = 24, plotter_filename: Optional[str] = None)[source]#

Animated visualization of 3D reconstruction model.

Parameters
models

A List of reconstructed models or a MultiBlock.

stable_model

The model that do not change with time in animation.

stable_kwargs

Parameters for plotting stable model. Available stable_kwargs are:

  • 'key'

  • 'ambient'

  • 'opacity'

  • 'model_style'

  • 'model_size'

  • 'background'

  • 'show_legend'

  • 'legend_kwargs'

  • 'show_outline'

  • 'outline_kwargs'

  • 'text'

  • 'text_kwargs'

key

The key under which are the labels.

filename

Filename of output file. Writer type is inferred from the extension of the filename.

  • Output a gif file, please enter a filename ending with .gif.

  • Output a mp4 file, please enter a filename ending with .mp4.

jupyter

Whether to plot in jupyter notebook. Available jupyter are:

  • 'none' - Do not display in the notebook.

  • 'pythreejs' - Show a pythreejs widget

  • 'static' - Display a static figure.

  • 'ipygany' - Show an ipygany widget

  • 'panel' - Show a panel widget.

off_screen

Renders off-screen when True. Useful for automated screenshots.

window_size

Window size in pixels. The default window_size is [512, 512].

background

The background color of the window.

cpo

Camera position of the active render window. Available cpo are:

  • Iterable containing position, focal_point, and view up.

    E.g.: [(2.0, 5.0, 13.0), (0.0, 0.0, 0.0), (-0.7, -0.5, 0.3)].

  • Iterable containing a view vector.

    E.g.: [-1.0, 2.0, -5.0].

  • A string containing the plane orthogonal to the view direction.

    E.g.: 'xy', 'xz', 'yz', 'yx', 'zx', 'zy', 'iso'.

colormap

Name of the Matplotlib colormap to use when mapping the scalars.

When the colormap is None, use {key}_rgba to map the scalars, otherwise use the colormap to map scalars.

ambient

When lighting is enabled, this is the amount of light in the range of 0 to 1 (default 0.0) that reaches the actor when not directed at the light source emitted from the viewer.

opacity

Opacity of the model.

If a single float value is given, it will be the global opacity of the model and uniformly applied everywhere, elif a numpy.ndarray with single float values is given, it will be the opacity of each point. - should be between 0 and 1.

A string can also be specified to map the scalars range to a predefined opacity transfer function (options include: ‘linear’, ‘linear_r’, ‘geom’, ‘geom_r’).

model_style

Visualization style of the model. One of the following:

  • model_style = 'surface',

  • model_style = 'wireframe',

  • model_style = 'points'.

model_size

If model_style = 'points', point size of any nodes in the dataset plotted.

If model_style = 'wireframe', thickness of lines.

show_legend

whether to add a legend to the plotter.

legend_kwargs

A dictionary that will be pass to the add_legend function. By default, it is an empty dictionary and the add_legend function will use the {"legend_size": None, "legend_loc": None,  "legend_size": None, "legend_loc": None, "title_font_size": None, "label_font_size": None, "font_family": "arial", "fmt": "%.2e", "n_labels": 5, "vertical": True} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

show_outline

whether to produce an outline of the full extent for the model.

outline_kwargs

A dictionary that will be pass to the add_outline function.

By default, it is an empty dictionary and the add_legend function will use the {"outline_width": 5.0, "outline_color": "black", "show_labels": True, "font_size": 16, "font_color": "white", "font_family": "arial"} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

text

The text to add the rendering.

text_kwargs

A dictionary that will be pass to the add_text function.

By default, it is an empty dictionary and the add_legend function will use the { "font_family": "arial", "font_size": 12, "font_color": "black", "text_loc": "upper_left"} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs.

framerate

Frames per second. Only available when filename ending with .mp4 or .gif.

plotter_filename

The filename of the file where the plotter is saved.

Writer type is inferred from the extension of the filename.

  • Output a gltf file, please enter a filename ending with .gltf.

  • Output a html file, please enter a filename ending with .html.

  • Output an obj file, please enter a filename ending with .obj.

  • Output a vtkjs file, please enter a filename without format.

spateo.plotting.static.three_d_plot.three_dims_plots.merge_animations(mp4_files: Optional[list] = None, mp4_folder: Optional[list] = None, filename: str = 'merged_animation.mp4')[source]#

Use MoviePy to compose a new animation and play multiple animations together in the new animation.

Parameters
mp4_files

A list containing absolute paths to mp4 files that need to be played together.

mp4_folder

Absolute path to the folder containing all mp4 files that need to be played together. If mp4_files is provided, mp4_folder cannot also be provided.

filename

Absolute path to save the newly composed animation.

Examples

st.pl.merge_animations(mp4_files=[“animation1.mp4”, “animation2.mp4”], filename=f”merged_animation.mp4”)