README

A strict, mathematical engine for Modular Scales. It handles the arithmetic of progressions, designed for generative design, typography engines, and rhythmic computation.

Installation

composer require alto/scale

Core Concepts

1. The Scale Facade

Use the Scale facade for fluent instantiation of any scale type.

use Alto\Scale\Scale;
use Alto\Scale\Ratio;

// Modular (Geometric): Base 16px, Ratio 1.25 (Major Third)
$type = Scale::majorThird(16.0);

// Linear (Arithmetic): Base 0, Increment 8
$grid = Scale::linear(0, 8);

// Fibonacci: Using Binet's formula
$fib = Scale::fibonacci();

// Multi-Strand: Interleaved scales (e.g., 16px and 12px strands)
$strands = Scale::strands([16, 12], Ratio::PerfectFifth);

2. Computing Values

All scales implement the ScaleInterface and are IteratorAggregate.

echo $type->get(0);  // 16.0
echo $type->get(1);  // 20.0
echo $type->get(-1); // 12.8

// ModularScale is callable
echo $type(2); // 25.0

Snapping (Normalization)

Find the nearest mathematical step for any arbitrary value.

// Returns 20.0 (The nearest step on a Major Third scale starting at 16)
$value = $type->snap(19.8);

Iteration & Ranges

// Scales are iterable (defaults to steps 0-10)
foreach ($type as $step => $value) {
    // ...
}

// Custom ranges
$values = $type->range(-2, 2);
// Returns: [-2 => 10.24, -1 => 12.8, 0 => 16.0, 1 => 20.0, 2 => 25.0]

3. The Guesser (Reverse Engineering)

Analyze messy datasets to find their underlying mathematical scale.

use Alto\Scale\Scale;
use Alto\Scale\ScaleGuesser;

$messyValues = [15.9, 20.1, 24.8, 31.5];

// Via the facade
$scale = Scale::guess($messyValues);

// Or directly with custom tolerance
$guesser = new ScaleGuesser(tolerance: 0.05);
$scale = $guesser->guess($messyValues);

// Align values to the guessed (or provided) scale
$aligned = $guesser->align($messyValues);

4. The Linter (Audit & Fix)

Audit datasets for scale compliance and automatically harmonize them.

use Alto\Scale\ScaleLinter;
use Alto\Scale\Scale;

$linter = new ScaleLinter(Scale::linear(0, 8));

// Get a detailed compliance report
$report = $linter->lint([8, 15, 24]);
// Each entry: ['original', 'suggested', 'step', 'deviation', 'isValid']

// Returns [8.0, 16.0, 24.0]
$fixed = $linter->fix([8, 15, 24]);

API Reference

Alto\Scale\Scale (Facade)

Alto\Scale\ScaleInterface

All scale classes (ModularScale, LinearScale, FibonacciScale, MultiStrandScale) implement:

Alto\Scale\ModularScale

Geometric progression: value = base * (ratio ^ step)

Alto\Scale\LinearScale

Arithmetic progression: value = base + (step * increment)

Alto\Scale\FibonacciScale

Fibonacci sequence using Binet's formula, with optional multiplier.

Alto\Scale\MultiStrandScale

Interleaved modular scales sharing a common ratio, useful for multi-strand typographic scales.

Alto\Scale\ScaleGuesser

Alto\Scale\ScaleLinter

Alto\Scale\Ratio (Enum)

Standard musical/typographic ratios:

License

This project is licensed under the MIT License.