GeViewer package

Interactive viewer

class geviewer.geviewer.GeViewer(filenames, destination=None, off_screen=False, safe_mode=False, no_warnings=False)

Bases: object

The main interface for the GeViewer application, responsible for loading, processing, and visualizing data files. This class manages the creation and display of 3D visualizations based on the provided data files and offers various functionalities such as toggling display options and saving sessions.

Parameters:

filenames (list of str) – A list of file paths to be loaded. Supported file formats include .gev and .wrl. Only the first file is used if multiple .gev files are provided.
destination (str, optional) – The file path where the session will be saved. If not provided, the session is not saved. The file extension must be .gev if specified.
off_screen (bool, optional) – If True, the plotter is created without displaying it. Defaults to False.
safe_mode (bool, optional) – If True, the viewer operates in safe mode with some features disabled.
no_warnings (bool, optional) – If True, suppresses warning messages. Defaults to False.

Raises:

Exception – If .gev and .wrl files are mixed, or if multiple .gev files are provided.
Exception – If attempting to save a session using an invalid file extension.

check_transparency(): Enables depth peeling if any of the meshes have transparency. This prevents issues with rendering order when displaying transparent objects.

create_plotter(): Creates a Plotter object, a subclass of pyvista.Plotter.

export_to_html(): Saves the interactive viewer to an HTML file, prompting the user for a file path.

load(filename)

Loads the meshes from a .gev file.

Parameters:: filename (str) – The path to the .gev file.
Raises:: Exception – Invalid file format. Only .gev files are supported.

plot_meshes(): Adds the meshes to the plot.

print_view_params(): Prints the current camera viewpoint parameters.

save(filename)

Saves the meshes to a .gev file.

Parameters:: filename (str) – The name of the file to save the session to.

save_screenshot(): Saves a screenshot of of the current view, prompting the user for a file path.

set_camera_view(args=None)

Sets the camera viewpoint.

Parameters:: args (list, optional) – A list of the view parameters, defaults to None

set_initial_view(): Sets the initial camera viewpoint based on the view parameters provided in the VRML file.

set_window_size(): Sets the size of the viewer window in pixels, prompting the user for the width and height.

show(): Opens the plotting window.

toggle_background(): Toggles the gradient background on and off.

toggle_step_markers(): Toggles the step markers on or off.

toggle_tracks(): Toggles the particle trajectories on or off.

toggle_wireframe(): Toggles between solid and wireframe display modes. Disables depth peeling if wireframe mode is enabled to improve responsiveness.

update_camera_position(): Updates the camera position. This method’s only job is to ensure that the PyVista plotter knows that the camera position has changed on a key event handled by vtk under the hood. This is necessary to avoid a bug where the camera jumps back to the isometric view the next time the user prints the camera position.

Command-line interface

geviewer.main.main()

Command line interface for GeViewer.

This function sets up the command-line interface for running the GeViewer application. It uses the argparse module to parse command-line arguments, allowing users to specify the files to be displayed and various options for running the viewer.

Command-line options include: - filenames: The file or list of files to be displayed. This argument is required. - -d or –destination: Optional argument specifying the path to save the session. If provided without a value, the default filename is ‘viewer.gev’. - -o or –off-screen: Optional flag to run the viewer in offscreen mode. - -s or –safe-mode: Optional flag to enable a more robust VRML parsing mode at the expense of some interactive features. - -w or –no-warnings: Optional flag to suppress warnings and prevent the program from pausing to display them.

geviewer.main.print_instructions(): Prints the banner and instructions for the user.

VRML parser

geviewer.parser.build_markers(blocks, pbar=None)

Builds a mesh for markers from given blocks of data.

This function processes blocks of marker data, creating a mesh of spheres for each marker.

Parameters:

blocks (list) – List of blocks containing marker data.
pbar (tqdm.tqdm, optional) – (Optional) A tqdm progress bar instance.

Returns:

The created mesh with combined centers, radii, and colors.

Return type:

pyvista.UnstructuredGrid

geviewer.parser.build_mesh(blocks, which, pbar=None)

Builds a mesh from given blocks of data.

This function processes blocks of data, creating a mesh based on the specified type (‘polyline’ or ‘solid’).

Parameters:

blocks (list) – List of blocks containing data for the mesh.
which (str) – Type of mesh to build (‘polyline’ or ‘solid’).
pbar (tqdm.tqdm, optional) – (Optional) A tqdm progress bar instance.

Returns:

The created mesh with combined points, cells, and colors.

Return type:

pyvista.PolyData

geviewer.parser.combine_mesh_arrays(points, cells, colors, pbar=None)

Combines multiple mesh arrays into a single mesh.

This function takes lists of points, indices of faces or line segments (called cells), and colors, and combines them into a single set of points, cells, and colors, adjusting indices appropriately.

Parameters:

points (list of numpy.ndarray) – A list of arrays containing point coordinates.
cells (list of list) – A list of lists containing cell indices.
colors (list of numpy.ndarray) – A list of arrays containing color data.
pbar (tqdm.tqdm, optional) – (Optional) A tqdm progress bar instance.

Returns:

A tuple containing three elements: - points (numpy.ndarray): Combined array of point coordinates. - cells (numpy.ndarray): Combined array of cell indices. - colors (numpy.ndarray): Combined array of color data.

Return type:

tuple

geviewer.parser.create_meshes(polyline_blocks, marker_blocks, solid_blocks)

Creates and returns meshes for polylines, markers, and solids.

This function processes blocks of data for polylines, markers, and solids, building corresponding meshes for each.

Parameters:

polyline_blocks (list) – List of blocks containing polyline data.
marker_blocks (list) – List of blocks containing marker data.
solid_blocks (list) – List of blocks containing solid data.

Returns:

A tuple containing three elements: - polyline_mesh (pyvista.PolyData): Mesh for polylines. - marker_mesh (pyvista.UnstructuredGrid): Mesh for markers. - solid_mesh (pyvista.PolyData): Mesh for solids.

Return type:

tuple

geviewer.parser.extract_blocks(file_content)

Extracts polyline, marker, and solid blocks from the given file content.

This function processes the provided file content, which is expected to be in a text format, and extracts blocks of different types based on specific keywords. It separates the blocks into categories: polyline, marker, and solid blocks, and also identifies the viewpoint block.

Parameters:: file_content (str) – The content of the file as a single string.
Returns:: A tuple containing four elements: - The viewpoint block (if found) as a string or None if not found. - A list of polyline blocks as strings. - A list of marker blocks as strings. - A list of solid blocks as strings.
Return type:: tuple

geviewer.parser.parse_marker_block(block)

Parses a marker block to extract the position, radius, and color of a marker.

This function processes a block of text representing a marker in a 3D scene description. It extracts the position of the marker, the radius of the marker (typically a sphere), and the color of the marker. It also accounts for transparency and adjusts the alpha value of the color accordingly.

Parameters:: block (str) – The marker block content as a string.
Returns:: A tuple containing: - coords: An array of shape (3,) representing the position of the marker in 3D space. - radius: A float representing the radius of the marker. - color: An array of four floats representing the RGBA color of the marker, where alpha is adjusted for transparency.
Return type:: tuple

geviewer.parser.parse_polyline_block(block)

Parses a polyline block to extract particle track information, including coordinates, indices, and color.

This function processes a block of text representing a polyline in a 3D scene description. It extracts the coordinates of the points that define the polyline, the indices that describe the lines between these points, and the color associated with the polyline.

Parameters:: block (str) – The polyline block content as a string.
Returns:: A tuple containing: - coords: An array of shape (N, 3) representing the coordinates of the polyline points. - indices: An array of integers representing the indices that define the polyline segments. - color: An array of four floats representing the RGBA color of the polyline, where the alpha is set to 1.
Return type:: tuple

geviewer.parser.parse_solid_block(block)

Parses a solid block to extract geometry information for a 3D solid object.

This function processes a block of text representing a solid object in a 3D scene description. It extracts the vertex coordinates, the face indices that define the geometry of the solid, and the color of the solid. The function also handles transparency by adjusting the alpha value in the color array.

Parameters:: block (str) – The solid block content as a string.
Returns:: A tuple containing: - coords: An array of shape (N, 3) where N is the number of vertices, representing the vertex coordinates. - coord_inds: An array of shape (M,) where M is the number of indices, representing the indices defining the faces of the solid. - color: An array of four floats representing the RGBA color of the solid, where the alpha value is adjusted for transparency.
Return type:: tuple

geviewer.parser.parse_viewpoint_block(block)

Parses the viewpoint block to extract the field of view, position, and orientation.

This function extracts the field of view (FOV), position, and orientation from a given viewpoint block in a 3D scene description. The FOV is converted from radians to degrees.

Parameters:: block (str) – The viewpoint block content as a string.
Returns:: A tuple containing: - The field of view in degrees as a float (or None if not found). - The position as a list of three floats [x, y, z] (or None if not found). - The orientation as a list of four floats [x, y, z, angle] in radians (or None if not found).
Return type:: tuple

geviewer.parser.process_marker_block(block)

Processes a marker block to create a marker mesh.

This function takes a block of marker data and creates a spherical marker mesh using PyVista. It also extracts the color information associated with the marker.

Parameters:: block (str) – The marker block content as a string.
Returns:: A tuple containing: - A pv.Sphere object representing the marker mesh. - The color associated with the marker mesh as a list or array.
Return type:: tuple

geviewer.parser.process_polyline_block(block)

Processes a polyline block to create a polyline mesh.

This function takes a block of polyline data and converts it into a PyVista`PolyData` object representing the polyline mesh. It also extracts the color information associated with the mesh.

Parameters:: block (str) – The polyline block content as a string.
Returns:: A tuple containing: - A pv.PolyData object representing the polyline mesh. - The color associated with the polyline mesh as a list or array.
Return type:: tuple

geviewer.parser.process_solid_block(block)

Processes a solid block to create a solid mesh.

This function takes a block of solid data and creates a mesh for a solid object using PyVista. It also extracts the color information associated with the solid.

Parameters:: block (str) – The solid block content as a string.
Returns:: A tuple containing: - A pv.PolyData object representing the solid mesh. - The color associated with the solid mesh as a list or array.
Return type:: tuple

Plotter

class geviewer.plotter.Plotter(*args, **kwargs)

Bases: Plotter

A custom plotter class that extends pyvista.Plotter to provide enhanced key event handling.

This class inherits from pyvista.Plotter and modifies key event handling to override specific key behaviors. Keys that are not overridden by this class will be passed to the original key event handler.

Parameters:

args – Positional arguments to pass to the base class constructor.
kwargs – Keyword arguments to pass to the base class constructor.

Methods:

geviewer_key_event: Handles key press events and overrides specific key behaviors.
show: Displays the plotter window with custom key event handling.

Inherited Methods:

pyvista.Plotter.show: Displays the plotter window.

geviewer_key_event(obj, event)

Handles key press events to override specific key behaviors.

This method intercepts key press events and checks if the key pressed is in the list of overridden keys. If it is, the method performs no action for these keys. For other keys, the method delegates the event to the original key event handler.

Parameters:

obj (vtkObject) – The VTK object that triggered the event.
event (str) – The event name (e.g., “CharEvent”).

show(*args, **kwargs)

Displays the plotter window with custom key event handling.

This method overrides the show method from pyvista.Plotter to include custom key event handling. It first sets up an observer for key press events and then calls the base class show method to displaythe plotter window.

Parameters:

args – Positional arguments passed to the base class show method.
kwargs – Keyword arguments passed to the base class show method.

Utilities

geviewer.utils.check_for_updates(): Determines whether the user is using the latest version of GeViewer. If not, prints a message to the console to inform the user.

geviewer.utils.clear_input_buffer()

Clears the input buffer to prevent stray keystrokes from influencing subsequent inputs.

Returns:: None

geviewer.utils.orientation_transform(orientation)

Calculate the up and camera direction vectors based on the orientation.

The function takes an orientation specified as a tuple or list (x, y, z, theta), where (x, y, z) is the axis of rotation and theta is the angle of rotation in radians. It applies this rotation to the default up vector (0, 1, 0) and the default direction vector (0, 0, -1) to compute the new up and direction vectors.

Parameters:: orientation (tuple or list of floats) – A tuple or list containing the axis of rotation and angle of rotation. The format is (x, y, z, theta), where (x, y, z) is the axis and theta is the rotation angle in radians.
Returns:: A tuple containing the transformed up vector and the transformed direction vector.
Return type:: tuple of (numpy.ndarray, numpy.ndarray)

async geviewer.utils.prompt_for_camera_view()

Asynchronously prompts the user for camera view input from the terminal.

This function prompts the user to enter the camera’s position, focal point, and up vector. Each input is expected to be a set of three comma-separated numbers. The function uses asynchronous input handling to avoid blocking other operations.

Returns:: A tuple containing the position, up vector, and focal point. Each value is a list of three floating-point numbers or None if the user skips the input.
Return type:: tuple

geviewer.utils.prompt_for_file_path()

Prompts the user for a file path to save the session.

This function asks the user to enter a file path where the session should be saved. The file path should end with the .gev extension to ensure compatibility with GeViewer for later loading of the session.

Returns:: The file path as a string if valid input is provided, or None if the input is canceled.
Return type:: str or None

async geviewer.utils.prompt_for_html_path()

Asynchronously prompts the user to input a file path for saving an HTML file.

This function prompts the user to enter a destination file path to save the viewer as an interactive HTML file.

Returns:: The file path provided by the user if valid, or None if the user presses enter to cancel.
Return type:: str or None

geviewer.utils.prompt_for_save_session(total_meshes)

Prompts the user to decide whether to save the session before loading a large file.

This function warns the user if the file they are attempting to view is large, based on the number of meshes (total_meshes). The user is given the option to save the current session to avoid reloading the file in the future.

Parameters:: total_meshes (int) – The number of meshes in the large file being loaded.
Returns:: A boolean indicating whether the session will be saved.
Return type:: bool

async geviewer.utils.prompt_for_screenshot_path()

Asynchronously prompts the user for a file path to save a screenshot.

This function prompts the user to enter a file path where the screenshot will be saved. The accepted file formats are .png, .svg, .eps, .ps, .pdf, and .tex. The function uses asynchronous input handling to avoid blocking other operations.

Returns:: The file path as a string if a valid path is provided, or None if the input is canceled.
Return type:: str or None

async geviewer.utils.prompt_for_window_size()

Asynchronously prompts the user for the window size.

This function prompts the user to enter the window size in pixels as two comma-separated integers, representing width and height. The function uses asynchronous input handling to avoid blocking other operations.

Returns:: A tuple containing the width and height as integers if valid input is provided, or (None, None) if the input is canceled.
Return type:: tuple of (int, int) or (None, None)

geviewer.utils.read_files(filenames)

Reads the content of multiple files and concatenates it into a single string.

Parameters:: filenames (list of str) – A list of file paths to read.
Returns:: A single string containing the concatenated content of all the files.
Return type:: str