Samurai Graph

A highly functional and user-friendly scientific graphing application for visualizing experimental data from various file formats.

Features

• Multi-format data import: CSV, NetCDF, HDF5, MATLAB (.mat) files
• Rich graph types: Single/Multiple XY, Date XY, Vector XY, Polar, Pseudocolor, (x,y,z) 3D data
• Image export: EMF, PDF, PostScript, SVG, SWF (via FreeHEP)
• Property files (.sgp): Save and reload graph configurations
• Archive files (.sga): Bundle data and properties together
• Script files (.sgs): Automate graph generation
• Native installers: Windows (.exe), macOS (.dmg), Linux (.deb, .rpm)
• JNA plugin system: Extend functionality with native libraries

System Requirements

• Java 21 or later
• NetCDF support:
  • Reading NetCDF-3 and NetCDF-4 files is handled by the NetCDF-Java reader bundled in the classpath and requires no system library.
  • Exporting data to a new NetCDF file writes NetCDF-3 and requires no system library.
  • Writing into an existing NetCDF-4 file (the Add Properties to NetCDF and Add Commands to NetCDF menu commands) goes through the JNA-backed NetCDF-C interface and does require the NetCDF-C library on the system.
    • Linux: libnetcdf-dev (Debian/Ubuntu), netcdf (Fedora/RHEL)
    • macOS: netcdf-c via Homebrew (brew install netcdf-c)
    • Windows: NetCDF-C redistributable must be installed and on PATH
    • Without it, opening, reading, and exporting still work; only writing into an existing NetCDF-4 file fails (an error is logged and the file is left unchanged).

Installation

Pre-built Installers

Download the latest release for your platform from the Releases page.

Platform	Format
Windows	.exe installer
macOS	.dmg disk image
Linux	.deb (Debian/Ubuntu) or .rpm (Fedora/RHEL)

Build from Source

./mvnw clean package

The executable fat JAR is created at target/samurai-graph-<version>.jar.

Usage

Launch the application:

java -jar target/samurai-graph-<version>.jar

Supported Data Formats

Format	Extension / Type
CSV / TSV	.txt, .csv (whitespace or comma delimited)
NetCDF	.nc
HDF5	.h5, .he5, .hdf5, .hdf
MATLAB	.mat (v5)

Graph Property Files

Graph configurations can be saved as .sgp files and reloaded later. Example property files are included in the examples/data/ directory.

Project Structure

samurai-graph/
├── src/main/java/       # Application source code
├── src/main/resources/  # Icons, properties, DTDs
├── src/main/assembly/   # jpackage input assembly descriptor
├── src/main/jpackage/   # Platform-specific installer resources
├── src/test/java/       # JUnit 5 test suite
├── plugins/jna/         # JNA native plugin (C source)
├── examples/data/       # Sample data and property files
├── changelog/           # Release notes (product.xml → ChangeLog.html)
└── pom.xml              # Maven build configuration

Development

Prerequisites

• Java 21 (JDK)
• Maven 3.9+ (or use the bundled Maven Wrapper: ./mvnw)

Build Commands

# Format code (Google Java Format via Spotless)
./mvnw spotless:apply

# Clean compile with lint checks
./mvnw clean compile

# Create fat JAR
./mvnw clean package

# Create native installer for the host OS (profile auto-activates; build on target OS)
# Windows:
./mvnw clean verify
# macOS:
./mvnw clean verify
# Linux (use non-distro JDK on Fedora/RHEL):
JAVA_HOME=/usr/lib/jvm/temurin-21-jdk ./mvnw clean verify

Testing

This project uses JUnit 5 (Jupiter) with the Maven Surefire plugin.

# Run all tests
./mvnw test

# Run a single test class
./mvnw -Dtest=SGPeriodTest test

The test suite covers utility and data classes in packages such as lib.mdarray, base, data, and figure.

See AGENTS.md for detailed contribution guidelines.

License

This project is licensed under the GNU Lesser General Public License v2.1.

Copyright (c) 2004-2026 RIKEN (The Institute of Physical and Chemical Research). All rights reserved.