Overview

Relevant source files

• .github/workflows/snap-build.yml
• CITATION.cff
• README.md
• generate_all.sh
• io.github.babaissarkar.ssplot.metainfo.xml
• snapcraft.yaml
• src/main/resources/download_msi.svg
• src/main/resources/filtered/project.properties
• src/main/resources/fonts/Inter-Regular.ttf
• src/main/resources/fonts/Inter-SemiBold.ttf

Purpose: This document provides a high-level introduction to SSPlot, describing its purpose, core capabilities, and architectural organization. It serves as an entry point for understanding the system before diving into specific subsystems.

For detailed information about specific areas:

• Installation procedures: see Installation and Setup
• Mathematical capabilities: see Mathematical Capabilities
• Technical implementation details: see Technical Architecture
• Build and deployment: see Development and Building

What is SSPlot?

SSPlot is a Java-based plotting utility and numerical simulator designed for visualizing mathematical data, solving differential and difference equations, and studying dynamical systems. The application provides both GUI and CLI interfaces for maximum flexibility.

Core Capabilities:

• 2D and 3D plotting of numerical datasets from CSV/text files
• Numerical solution of ordinary differential equations (ODEs) using RK4 integration
• Difference equation iteration for discrete dynamical systems
• Function plotting for single and multi-variable functions
• Specialized visualizations including direction fields, cobweb diagrams, and vector fields
• Interactive manipulation with zoom, pan, and rotation controls
• Scripting console supporting JavaScript and Python (via JSR-223 engines)

Sources: io.github.babaissarkar.ssplot.metainfo.xml20-30 README.md1-6

System Architecture Overview

SSPlot is organized into five major subsystems that handle distinct responsibilities:

Sources: src/main/java/com/babai/ssplot/ui/MainFrame.java66-247 src/main/java/com/babai/ssplot/cli/SSPlotCLI.java

Application Entry Points

SSPlot provides two operational modes controlled by command-line arguments:

Mode	Entry Point	Primary Use Case	Key Classes
GUI Mode	MainFrame.main()	Interactive plotting and equation solving	MainFrame, SystemInputFrame, PlotView
CLI Mode	SSPlotCLI.main()	Batch processing and REPL calculations	SSPlotCLI, NumParse, CLILogger

The mode selection occurs in src/main/java/com/babai/ssplot/ui/MainFrame.java485-489:

Sources: src/main/java/com/babai/ssplot/ui/MainFrame.java485-510

Core Subsystems

User Interface Layer

The GUI is built on a multi-document interface (MDI) architecture with JDesktopPane hosting internal frames:

The application window structure is initialized in src/main/java/com/babai/ssplot/ui/MainFrame.java86-247 Each internal frame serves a specific purpose:

• SystemInputFrame: Configures equations, parameters, ranges, and system modes
• DataView: Displays computed or loaded data in tabular form with editing capabilities
• PlotFrame: Contains PlotView and toolbar controls for zoom/rotation
• PlotView: JLabel subclass that renders the BufferedImage from Plotter

Sources: src/main/java/com/babai/ssplot/ui/MainFrame.java86-247 src/main/java/com/babai/ssplot/ui/PlotView.java45-92 src/main/java/com/babai/ssplot/ui/PlotFrame.java27-159 src/main/java/com/babai/ssplot/ui/DataView.java58-200

Mathematical Processing Pipeline

The mathematical engine transforms equations into numerical data through a multi-stage pipeline:

The pipeline begins when a user clicks a plot button in SystemInputFrame, which:

1. Builds an EquationSystem from input fields
2. Obtains a Parser via ParserManager
3. Instantiates a Solver with the parser and system
4. Calls appropriate numerical method (e.g., rk4Iterate() for ODEs)
5. Wraps results in PlotData with metadata

Sources: src/main/java/com/babai/ssplot/math/system/EquationSystem.java src/main/java/com/babai/ssplot/math/parser/ParserManager.java src/main/java/com/babai/ssplot/math/methods/Solver.java

Visualization Engine

The rendering subsystem transforms PlotData into displayable graphics:

Key rendering methods:

• Plotter.plot(): Orchestrates the rendering based on PlotType enum
• Project2D.project(): Applies rotation matrices for 3D visualization
• Canvas.cartesianToJava(): Transforms mathematical coordinates to pixel coordinates
• Canvas drawing methods: Low-level graphics primitives for points, lines, vectors, axes

The final BufferedImage is displayed by PlotView via src/main/java/com/babai/ssplot/ui/PlotView.java95-121

Sources: src/main/java/com/babai/ssplot/math/plot/Plotter.java src/main/java/com/babai/ssplot/math/plot/Canvas.java src/main/java/com/babai/ssplot/math/plot/Project2D.java src/main/java/com/babai/ssplot/ui/PlotView.java95-121

Data Flow Summary

The complete data flow from user input to visualization follows this sequence:

Stage	Component	Input	Output	Key Method
Configuration	SystemInputFrame	User equation strings	EquationSystem	build()
Parsing	ParserManager	Equation strings	Parser instance	getParser()
Computation	Solver	Equations + parameters	double[][]	rk4Iterate() / iterateMap()
Wrapping	PlotData constructor	Raw data array	PlotData	new PlotData(data)
Rendering	Plotter	PlotData	BufferedImage	plot()
Display	PlotView	BufferedImage	Visual output	paint()

Update callbacks maintain bidirectional synchronization between SystemInputFrame, DataView, and PlotView, as established in src/main/java/com/babai/ssplot/ui/MainFrame.java118-130:

Sources: src/main/java/com/babai/ssplot/ui/MainFrame.java116-130

Technology Stack

SSPlot is built using the following core technologies:

Component	Technology	Purpose
Language	Java 17+	Core implementation
Build System	Maven	Dependency management and packaging
Parser Generator	JavaCC	Mathematical expression parsing
UI Framework	Swing	GUI components
UI Theme	FlatLaf	Modern look-and-feel
Script Engines	JSR-223 (Rhino/Jython)	External expression parsers
Packaging	JPackage	Platform-specific installers
CI/CD	GitHub Actions	Automated builds

Distribution formats:

• Windows: MSI installer (bundled JRE)
• Linux: DEB, AppImage (bundled JRE), Flatpak, Snap
• Cross-platform: Executable JAR

Build configuration is defined in pom.xml and orchestrated by generate_all.sh1-14 for Linux packages.

Sources: README.md8-51 generate_all.sh1-14 pom.xml

File Organization

The codebase follows a standard Maven project structure:

src/main/java/com/babai/ssplot/
├── cli/              # Command-line interface
├── math/             # Mathematical engine
│   ├── methods/      # Numerical solvers
│   ├── parser/       # Expression parsing
│   ├── plot/         # Plotting and rendering
│   └── system/       # Equation system configuration
├── ui/               # GUI components
│   ├── controls/     # Reactive UI framework
│   └── help/         # Documentation viewer
└── util/             # Utilities (logging, file I/O, system info)

Key files:

• src/main/java/com/babai/ssplot/ui/MainFrame.java: Application entry point
• src/main/java/com/babai/ssplot/math/plot/Plotter.java: Rendering orchestrator
• src/main/java/com/babai/ssplot/math/methods/Solver.java: Numerical methods
• src/main/java/com/babai/ssplot/math/parser/ParserManager.java: Parser selection

Sources: Project directory structure

License and Attribution

SSPlot is licensed under LGPL 2.1 or later. The bundled Inter font uses the SIL Open Font License 1.1.

Sources: README.md77-79 io.github.babaissarkar.ssplot.metainfo.xml8-9