scatter-cli

The official Python command-line wrapper for the Scattering Core Java library.

This package provides a frictionless way to install and execute the CLI directly from the Python environment or terminal, bypassing manual JAR downloads.

Requirements

Because this package bundles and delegates commands to the underlying Java executable, you must have JRE 21+ installed and accessible in your system's PATH.

Installation

Install the package globally or in a virtual environment via pip:

pip install scatter-cli

Alternatively, you can run the CLI instantly without installing it using pipx:

pipx run scatter-cli --info

Getting started

Once installed, both scatter-cli and the scatter-vis 3D viewer are globally available in your terminal.

To verify your setup, use the built-in demo command. It generates a standard Cluster-Cluster (CC) aggregate composed of 2,048 primary particles with fractal parameters df=1.8 and kf=1.3, exported in the multisphere format.

scatter-cli demo > demo.xyzr        # Save assembly to a file.
scatter-cli demo | scatter-vis      # Show a 3D model of the assembly.

Currently, the scatter-vis utility exclusively supports data streams in the multisphere format.

Usage

Here is a quick workflow demonstrating how to generate a custom synthetic fractal-like aggregate model and measure its morphological properties:

# Generate a Diffusion-Limited Aggregation (DLA) fractal-like aggregate model and save it to a file.
scatter-cli generate model pc dla --rad-fixed 2048,1 --export multisphere --out demo.xyzr
# Measure the Density-Correlation (DC) fractal dimension of the generated model.
scatter-cli measure demo.xyzr --metrics df-dc -i multisphere

Fig 1: PC DLA synthetic fractal-like aggregate model.

Documentation

This Python package is a thin distribution wrapper maintained as part of the larger scattering.core ecosystem. To avoid duplication, comprehensive documentation, algorithmic details, and advanced usage examples are hosted on the main repository:

• Project Documentation
• CLI-Specific Documentation