app.widgets.main package

Submodules

app.widgets.main.frame_visualiser module

class app.widgets.main.frame_visualiser.Visualizer3DWidget(scene_data, project_folder, angles, parent=None)

Bases: QWidget

Visualizer3DWidget Class

A PyQt5-based widget for interactive 3D visualization and playback of flapping-wing Micro Aerial Vehicle (MAV) simulation data. This widget serves as a real-time visual tool to inspect spatial orientation, transformations, and local/global coordinate systems derived from simulation frames.

The widget includes: - A VTK-based 3D scene viewer. - Playback controls (play, pause, next frame). - A slider to scrub through simulation frames. - Global and per-object body axes visualizations.

scene_data

Parsed simulation object containing geometry, frame orientations, and object transformations.

Type:

object

project_folder

Path to the project directory containing configuration and assets.

Type:

str

angles

List of orientation angles for animation frames.

Type:

List[float]

reflect

Boolean flags indicating whether XY, YZ, or XZ axis reflections are active, derived from the project’s config file.

Type:

List[bool]

actor

The VTK actor representing the primary STL mesh of the scene.

Type:

vtk.vtkActor

body_axes

List of per-object axes actors, visualizing local coordinate systems.

Type:

List[vtk.vtkAxesActor]

vtkWidget

VTK widget integrated into the PyQt5 layout for rendering the 3D scene.

Type:

QVTKRenderWindowInteractor

ren

Renderer instance that manages visual elements and camera.

Type:

vtk.vtkRenderer

iren

Interactor for handling user input and real-time navigation.

Type:

vtkRenderWindowInteractor

slider

Slider for frame-by-frame navigation through animation data.

Type:

QSlider

slider_label

Label displaying the currently selected frame index.

Type:

QLabel

play_button

Button to toggle playback of the simulation.

Type:

QPushButton

next_button

Button to jump to the next frame in the sequence.

Type:

QPushButton

playing

Internal flag indicating whether playback is active.

Type:

bool

__init__(scene_data, project_folder, angles, parent=None)

Initialize the widget and prepare UI and visualization pipeline.

init_ui()

Set up the UI layout, controls, slider, buttons, and VTK window.

setup_visualization()

Load configuration, generate VTK mesh and actors, initialize the scene.

create_axes_actor(poly_data)

Create a global coordinate axes actor scaled to mesh bounds.

create_body_axes(sprite)

Generate a local coordinate system actor for a given object.

toggle_play()

Toggle animation playback state and update play button icon.

play_frames()

Play the animation by advancing the frame slider on a timer.

on_slider_value_changed()

Update the scene actors according to the selected frame.

stl_mesh_to_vtk(stl_mesh)

Convert an STL mesh from numpy-stl format to VTK polydata.

create_axes_actor(poly_data)

Create and configure a global coordinate axes actor based on the bounding box of the given mesh.

Parameters:

poly_data (vtk.vtkPolyData) – The VTK polydata object representing the mesh from which the bounds are calculated.

Returns:

The axes actor with scaled dimensions and labeled axes (‘X’, ‘Y’, ‘Z’).

Return type:

vtk.vtkAxesActor

Notes

• The axes size is set to 10% of the maximum bounding box dimension.

• Axis labels are set and styled with black color for readability.

• This actor provides a visual reference for global orientation in the 3D scene.

create_body_axes(sprite)

Create a local coordinate axes actor for a given sprite object, oriented and positioned based on its frame orientation and origin.

Parameters:

sprite (object) – A sprite object from the scene containing frame orientation and origin attributes.

Returns:

A VTK axes actor positioned and rotated according to the sprite’s local frame.

Return type:

vtk.vtkAxesActor

Notes

• The axis labels are set to ‘A’, ‘B’, and ‘C’ to represent the object’s local coordinate system.

• The axis size is scaled relative to the mesh bounds for proportional rendering.

• Orientation is applied using Euler angles (in radians), converted to degrees for VTK.

• This actor visually represents the local transformation of each object in the scene.

init_ui()

Initialize the user interface components of the 3D visualizer widget.

Sets up the layout, playback controls, VTK rendering window, and prepares the visualization pipeline for the flapping MAV simulation.

UI Components:

• Frame slider with frame label for time-step control.

• Play/pause button and next-frame button.

• Embedded VTK render window for 3D scene visualization.

This method also calls setup_visualization() to initialize the rendering pipeline.

on_slider_value_changed()

Update the visualization based on the current slider frame index.

This method retrieves the frame-specific orientation and position data for each object, computes their transformation matrices, and updates the corresponding VTK actors accordingly. The slider label is also updated to reflect the current frame index.

Notes

• Applies both translation and rotation to each actor and its associated body axes.

• Updates the main mesh actor (self.actor) transformation based on the last processed object.

• Triggers a re-render of the VTK render window.

play_frames()

Advance the animation by one frame and schedule the next frame if playing.

This method increments the frame slider to the next value, wraps around at the end, and updates the visualization accordingly. If playback is active, it recursively schedules the next frame update using a QTimer.

Notes

• Frame updates occur every 50 milliseconds.

• The method stops updating if self.playing is set to False.

setup_visualization()

Set up the 3D visualization environment using VTK.

This method loads the reflection configuration from the project JSON, converts the scene’s STL mesh to VTK-compatible format, initializes the main actor and coordinate axes, and prepares the interactor for rendering.

Steps performed:

• Load config.json to determine reflection plane settings.

• Generate and convert the scene mesh using save_stl() and stl_mesh_to_vtk().

• Create and configure the VTK actor with color and opacity.

• Initialize global coordinate axes and per-object body axes.

• Add all actors to the renderer and reset the camera.

• Initialize the VTK interactor for user interaction.

Raises:

FileNotFoundError

If config.json does not exist in the project folder.

JSONDecodeError

If the JSON configuration file is improperly formatted.

stl_mesh_to_vtk(stl_mesh)

Convert an STL mesh (numpy-stl) into a VTK vtkPolyData object.

Parameters:

stl_mesh (stl.mesh.Mesh) – The mesh object from the numpy-stl library containing triangle vectors.

Returns:

The converted mesh as a VTK polydata object with points and triangle cells.

Return type:

vtk.vtkPolyData

Notes

• Deduplicates vertices before inserting them into the VTK point list.

• Ensures mesh connectivity by using indexed triangles.

toggle_play()

Toggle the playback state of the animation and update the play button icon accordingly.

This method switches between playing and paused states. When toggled to play, it initiates the frame-by-frame animation using the play_frames() method.

Side Effects

• Updates self.playing to reflect the current playback state.

• Changes the play button icon to either a play or pause symbol depending on the state.

• Starts frame playback if toggled to playing.

Notes

• The icon is styled using the widget’s foreground color for visual consistency.

app.widgets.main.point_visualiser module

class app.widgets.main.point_visualiser.PointScatterWidget(scene_data, parent=None)

Bases: QWidget

PointScatterWidget Class

A composite PyQt5 widget that enables interactive point selection on a flattened STL mesh and visualizes the 3D transformed trajectory of the selected point across animation frames.

The interface is vertically split into two VTK-based views: - A 2D flattened STL view for selecting points. - A 3D scatter plot for observing the point’s transformation over time using scene data.

This widget is designed to plug into the main FlapKine interface for analyzing how specific points evolve under dynamic transformations like translation, rotation, and flexibility.

scene_data

The scene object containing STL mesh data and time-varying transformation functions (translation, rotation, flexibility) used to compute point trajectories.

Type:

SceneData

splitter

Vertical splitter separating the selection view (top) from the 3D scatter view (bottom).

Type:

QSplitter

toprightgroup

Container for the top VTK viewport showing the flattened STL mesh for point selection.

Type:

QGroupBox

bottomrightgroup

Container for the bottom VTK viewport displaying the 3D scatter plot of transformed points.

Type:

QGroupBox

vtk_widget_1

VTK widget for displaying and interacting with the flattened STL mesh.

Type:

QVTKRenderWindowInteractor

vtk_widget_2

VTK widget for displaying the resulting 3D point trajectory visualization.

Type:

QVTKRenderWindowInteractor

ren_1

VTK renderer for the flattened STL mesh view.

Type:

vtkRenderer

ren_2

VTK renderer for the 3D scatter plot view.

Type:

vtkRenderer

iren_1

Interactor for handling mouse events in the selection viewport.

Type:

vtkRenderWindowInteractor

iren_2

Interactor for the 3D scatter plot view.

Type:

vtkRenderWindowInteractor

interactor_style_1

Interactor style configured for precise point picking on the STL mesh.

Type:

vtkInteractorStyleImage

last_marker_actor

Actor representing the most recently selected point as a sphere.

Type:

vtkActor or None

last_outline_actor

Outline actor surrounding the last marker for visual emphasis.

Type:

vtkActor or None

scatter_actor

Actor representing the full 3D trajectory of the selected point across animation frames.

Type:

vtkActor or None

__init__(scene_data, parent=None)

Initializes the widget with the scene data and invokes the UI construction.

init_ui()

Constructs the layout, initializes the VTK viewports, and renders the STL mesh.

on_click(obj, event)

Handles mouse click events on the STL mesh and computes the 3D point trajectory.

add_marker_to_vtk(position)

Places a visual marker and outline at the selected point in the 2D STL view.

create_3d_scatter_plot(initial_point)

Computes and renders the 3D trajectory of the selected point using transformation functions.

stl_mesh_to_vtk(stl_mesh)

Converts a NumPy-based STL mesh into a VTK PolyData object for rendering.

add_marker_to_vtk(position)

Adds a visual marker to the 2D STL view at the selected 3D position.

This method renders a red 3D sphere and a semi-transparent white outline sphere at the specified position to visually indicate a user-selected point on the mesh. If a previous marker exists, it is removed before placing the new one. This enhances visual feedback for user interactions.

Parameters:

• position (tuple[float, float, float]) – A 3D coordinate (x, y, z) representing the location where the marker should be placed on the STL mesh.

• Elements (Visual)

• ---------------

• Marker (- Main) –

  • Shape: Red sphere

  • Radius: 0.08 units

  • Appearance: Glossy with specular highlights

• Outline (-) –

  • Shape: Larger semi-transparent white sphere

  • Radius: 0.1 units

  • Appearance: Faint glow effect to increase visibility

• Behavior

• --------

• actors. (- Replaces any previously placed marker by removing old)

• ren_1. (- Adds both new actors to the renderer)

• update. (- Refreshes the render window for immediate visual)

Notes

• Marker is placed in the same renderer (ren_1) used for the STL mesh.

• Used in conjunction with on_click() for interactive point selection.

create_3d_scatter_plot(initial_point)

Generates and renders a 3D scatter plot of a selected point’s trajectory over time.

This method computes and visualizes the dynamic 3D trajectory of a selected point from its 2D projection using the object’s transformation pipeline: flexibility, rotation, and translation. It draws the resulting points as blue spheres and overlays 3D axes for spatial reference.

Parameters:

• initial_point (tuple[float, float, float]) – The initial 3D coordinates (flattened on the Z-axis) selected from the STL mesh.

• Pipeline (Transformation)

• -----------------------

• flexibility_transform (-)

• rotation_transform (-)

• translation_transform (-)

• Details (Visualization)

• ---------------------

• sphere. (- Each transformed point is rendered as a blue)

• evolution. (- All points form a dynamic scatter plot indicating the point's temporal)

• orientation (- A 3D axes actor is added to aid with) –

  • X-axis: Red

  • Y-axis: Green

  • Z-axis: Blue

• Behavior

• --------

• one. (- Removes any existing scatter plot actor before drawing the new)

• (ren_2). (- Adds the generated actor and axes to the secondary VTK renderer)

• plot. (- Resets and updates the camera to ensure proper view of the rendered)

Notes

• Intended to be triggered after a point selection in the top STL view.

• Integrates tightly with transformation data embedded in the scene structure.

init_ui()

Builds the UI layout and initializes VTK visualization panels.

This method constructs the vertical layout of the PointScatterWidget, including two main interactive viewports arranged using a QSplitter. The top panel displays a flattened 2D projection of the STL mesh for point selection, while the bottom panel is configured to render the 3D trajectory scatter plot corresponding to the selected point. The method also sets up the required VTK renderers, interactor styles, and loads the STL mesh from the provided scene data.

UI Components

• QSplitter (Vertical):

  • Top GroupBox (“Selected Point”):

    • Contains QVTKRenderWindowInteractor for showing 2D STL projection

    • Handles mouse click events for point picking

  • Bottom GroupBox (“3D Scatter Plot”):

    • Contains QVTKRenderWindowInteractor for rendering 3D trajectories

VTK Setup

• Renderer for top view (ren_1) with background color set

• Interactor style set to vtkInteractorStyleImage for 2D point interaction

• STL mesh converted via stl_mesh_to_vtk() and flattened along Z-axis

• Loaded mesh displayed using vtkPolyDataMapper and vtkActor

• Renderer for bottom view (ren_2) initialized for dynamic scatter plotting

Notes

• The left mouse button is connected to on_click() to allow user-driven point selection

• The bottom view remains empty until a point is selected and a trajectory is computed

• Stretch factors control the vertical space allocated to each panel (top: 3, bottom: 2)

on_click(obj, event)

Handles left mouse button click event on the 2D STL view.

This method is triggered when the user clicks on the top VTK viewport displaying the 2D projection of the STL mesh. It uses vtkCellPicker to convert the screen click coordinates into a 3D position on the mesh surface. The selected point is then used to both visualize a trajectory scatter plot in 3D space and mark the clicked location on the mesh.

Parameters:

• obj (vtkObject) – The VTK interactor object that captured the click event.

• event (str) – A string describing the type of VTK event (e.g., “LeftButtonPressEvent”).

• Flow (Processing)

• ---------------

• interactor (- Extract screen-space click coordinates from the VTK)

• point (- Call add_marker_to_vtk(picked_pos) to highlight the selected)

• coordinates (- Retrieve the picked 3D world)

• trajectories (- Call create_3d_scatter_plot(picked_pos) to display)

• point

Notes

• Picker tolerance is set to 0.005 for precision in point selection

• This method assumes that a valid STL mesh is already rendered in ren_1

stl_mesh_to_vtk(stl_mesh)

Converts an STL mesh into a VTK-compatible vtkPolyData object.

This method transforms a NumPy-based STL mesh, typically from numpy-stl, into VTK’s vtkPolyData format. It ensures unique vertex mapping and constructs triangular cell connectivity for accurate 3D rendering within the VTK pipeline.

Parameters:

stl_mesh (stl.mesh.Mesh) – The STL mesh object containing 3D geometry as triangle vectors, usually loaded using the numpy-stl library (stl.mesh.Mesh.from_file()).

Returns:

• vtk.vtkPolyData – A vtkPolyData object representing the same geometry, with deduplicated vertices and properly constructed triangle cells suitable for VTK visualization.

• Process

• ——-

• • Deduplicates all vertices in the STL using np.unique to ensure compact geometry.

• - Reconstructs triangle connectivity using the deduplicated vertex indices.

• • Stores all vertex and triangle data in a new vtkPolyData object.

Notes

• Ensures VTK-friendly format for further processing such as rendering or transformation.

• Especially useful when integrating STL models into PyQt + VTK GUI applications.

app.widgets.main.video_animation module

class app.widgets.main.video_animation.VideoAnimation(project_folder, scene_data, parent=None)

Bases: QWidget

VideoAnimation Class

A PyQt5-based widget for interactive video playback and 3D frame rendering using precomputed animation data. This class serves as a control center for reviewing and exporting animations produced from dynamic scene transformations within the FlapKine environment.

The widget includes: - A video player for previewing rendered videos. - Playback controls (play, pause, repeat). - A slider for timeline navigation. - A render button to generate video frames using transformation data. - A progress bar to monitor rendering status.

project_folder

Path to the project directory containing configuration and output files.

Type:

str

scene_data

The scene object containing transformation functions (angles, rotation, translation) used to generate frame-wise data.

Type:

SceneData

angles

List of rotation angles associated with the current scene, used during frame rendering.

Type:

List[float]

reflect

Boolean flags indicating which axes (XY, YZ, XZ) are to be reflected during rendering, derived from config settings.

Type:

List[bool]

video_playing

Internal flag tracking the current playback state.

Type:

bool

primary_color

Primary color extracted from the application palette, used to style UI icons.

Type:

str

video_widget

Custom widget responsible for loading and displaying the rendered video.

Type:

VideoPlayer

playButton

Toggle button to control video playback (play/pause).

Type:

QPushButton

repeatButton

Toggle button to enable or disable repeat mode after video ends.

Type:

QPushButton

positionSlider

Slider for seeking through video frames.

Type:

QSlider

render_button

Button to initiate frame rendering based on scene transformations.

Type:

QPushButton

progress_bar

Visual indicator of the frame rendering progress.

Type:

QProgressBar

config

Dictionary holding video configuration (e.g., resolution), loaded from config.json.

Type:

dict

worker

Background thread responsible for generating frames during rendering.

Type:

Worker

__init__(project_folder, scene_data, parent=None)

Initializes the video animation widget and sets up the UI, configuration, and media loading.

_loadConfig()

Loads video rendering configuration from the project’s config.json file.

_createWidgets()

Creates and configures all internal widgets, including video player, buttons, and sliders.

_createLayout()

Arranges the UI components using QVBoxLayout and QHBoxLayouts for control and render sections.

_connectSignals()

Connects UI signals to their corresponding slot functions for interactive behavior.

_loadMedia()

Loads the rendered video from the project directory, if it exists.

_showError(message)

Displays or logs an error when video loading or configuration fails.

playVideo()

Toggles between play and pause states for the video.

repeatVideo()

Enables or disables repeat mode and restarts playback if enabled.

updateDuration(duration)

Updates the slider’s maximum range based on the video’s total duration.

updatePosition(position)

Updates the slider position based on current playback frame.

setPosition(position)

Sets the video’s current position based on slider interaction.

updateState(state)

Reacts to the media player’s state change and auto-repeats video if required.

update_progress(value)

Updates the progress bar’s value during frame rendering.

genframes()

Starts the rendering worker thread to compute and export video frames.

complete_render()

Handles cleanup and UI updates after rendering is complete and reloads the new video.

complete_render()

Finalizes the rendering process and updates the UI.

Re-enables the render button, displays a confirmation dialog with the output video path, and reloads the rendered video into the video player for immediate preview.

Post-Render Actions:

• Enables render_button for future rendering.

• Displays alert with the final video path.

• Loads the new video into video_widget using setMedia().

genframes()

Starts the frame rendering process using a background worker thread.

Initializes a Worker instance with the current scene parameters and begins the rendering task asynchronously. Disables the render button during processing and connects progress and completion signals for real-time UI feedback.

Workflow:

• Disables render_button to prevent multiple triggers.

• Instantiates Worker with project_folder, angles, scene_data, and reflect.

• Connects progress_signal to update_progress() for live updates.

• Starts the worker thread to render frames.

• Connects finished signal to complete_render() for post-processing and cleanup.

playVideo()

Toggles video playback state between play and pause.

Handles the core play/pause logic based on the internal video_playing flag. Updates both the media player’s state and the icon displayed on the play button to reflect the current action.

Behavior:

• If video is playing: pauses playback and updates button to ‘play’ icon.

• If video is paused: starts playback and updates button to ‘pause’ icon.

Updates:

• video_playing flag

• playButton icon using QtAwesome with primary UI color

repeatVideo()

Toggles repeat mode for the video playback.

Checks the state of the repeatButton and updates the repeat icon accordingly. If repeat mode is enabled, the video restarts from the beginning and begins playback immediately. If disabled, it simply reverts the icon to the repeat state.

Behavior:

• If checked: sets icon to repeat-off, resets position to start, and plays the video.

• If unchecked: sets icon back to repeat.

UI Updates:

• repeatButton icon

• playButton icon (set to ‘pause’ if playback is restarted)

setPosition(position)

Sets the media player to the given position.

Parameters:

position (int) – New playback position in milliseconds.

showAlertDialog(title, message)

Displays an informational alert dialog with the given title and message.

Presents a modal QMessageBox configured to convey general information to the user. Commonly used for confirmations, status updates, or non-critical notices.

Parameters:

• title (str) – The title text displayed on the alert dialog window.

• message (str) – The information content shown inside the dialog.

showErrorDialog(title, message)

Displays a critical error dialog with the specified title and message.

Creates and shows a modal QMessageBox configured to indicate an error condition. Typically used to alert users when essential files or configurations are missing.

Parameters:

• title (str) – The title text displayed on the error dialog window.

• message (str) – The detailed error message shown within the dialog content.

updateDuration(duration)

Updates the slider range based on video duration.

Parameters:

duration (int) – Total duration of the video in milliseconds.

updatePosition(position)

Updates the slider’s value to match the current playback position.

Parameters:

position (int) – Current position of the video in milliseconds.

updateState(state)

Handles media state changes and auto-repeats video if in repeat mode.

Parameters:

state (QMediaPlayer.State) – Current state of the media player.

update_progress(value)

Updates the progress bar with the given value.

Parameters:

value (int or float) – Current progress percentage (0–100).

Module contents