Joular Viewer

Joular Viewer is a modern native desktop application for inspecting energy and power traces generated by Joular Code Java. It keeps the analysis local, offline, and cross-platform while providing a cleaner workstation-style interface for branches, methods, timelines, and distribution charts.

Highlights

• Native PySide6 desktop app for Windows, macOS, Linux, and Raspberry Pi.
• Overview dashboard with total energy, rows, branches, methods, duration, peak power, top contributors, and a compact timeline.
• Searchable and sortable branch/method tables with raw numeric sorting, energy share percentages, tooltips for long names, and row copy support.
• Resizable analysis shell with a command bar, navigation rail, timeline view, distribution charts, and a collapsible inspector.
• Light, dark, and system theme modes with persisted preferences.
• Drag-and-drop CSV loading, recent files, last-file restore, persisted window geometry, splitter sizes, and Top N setting.
• Full export bundle: CSV summaries, Markdown summaries, PNG chart/table renders, and analysis_summary.json.
• Compatibility launcher: python power_analysis_gui.py still works.

Install

Python 3.11 or later is required.

pip install -r requirements.txt

For development and packaging:

pip install -r requirements-dev.txt

Launch

Run the compatibility script:

python power_analysis_gui.py

Run as a module:

python -m joular_viewer methods-power-app.csv

After installing the project, run the console entry point:

joular-viewer methods-power-app.csv

If no file is provided, the app restores the last opened file when possible, or loads methods-power-app.csv from the current directory when it exists.

Workflow

1. Open a Joular CSV with Open, drag a CSV onto the window, or choose a file from Open Recent.
2. Use the left navigation rail to move between Overview, Branches, Methods, Timeline, and Distribution.
3. Filter Branches or Methods with the search field. Click a row to inspect its statistics and focused power chart.
4. Adjust Top N to change the number of series displayed in the timeline.
5. Export the analysis bundle with Export or Ctrl+E.

Input CSV Format

The viewer expects the CSV columns produced by Joular Code Java:

timestamp,branch,power_watts,energy_joules,interval_seconds

Column	Type	Description
timestamp	integer milliseconds	Unix timestamp at the end of the monitoring cycle
branch	string	Semicolon-separated call chain
power_watts	float	Estimated power consumed during the cycle
energy_joules	float	Energy for the cycle
interval_seconds	float	Duration of the monitoring cycle

Both methods-power-app.csv and methods-power-all.csv style outputs are supported.

Keyboard Shortcuts

Shortcut	Action
Ctrl+O	Open CSV
Ctrl+R	Reload current CSV
Ctrl+E	Export analysis bundle
Ctrl+I	Toggle inspector
Ctrl+C	Copy the selected table row

Project Layout

• power_analysis_gui.py - compatibility launcher.
• joular_viewer/analysis.py - CSV loading, validation, aggregation, and analysis data types.
• joular_viewer/ui/ - PySide6 window, table models, themes, widgets, and matplotlib figure factories.
• joular_viewer/exporters.py - CSV, Markdown, PNG, and JSON export bundle.
• tests/ - analysis, export, and GUI smoke tests.
• packaging/ - PyInstaller spec and platform build scripts.

Packaging

PyInstaller builds must be produced on the target operating system. The scripts below create local build/ and dist/ directories for the current platform; they do not cross-compile.

Windows:

.\packaging\windows\build.ps1

macOS:

bash packaging/macos/build.sh

Linux:

bash packaging/linux/build.sh

Tests

pytest

The GUI smoke test uses Qt offscreen mode. Manual acceptance should also include loading the bundled methods-power-app.csv, trying a large CSV, checking theme switching, confirming drag-and-drop, and opening the exported files.

License

Joular Viewer is licensed under the GNU GPL 3 license only (GPL-3.0-only).

Copyright (c) 2026, Adel Noureddine.

Author: Prof. Adel Noureddine