diff options
Diffstat (limited to 'morphology-img/README.md')
| -rw-r--r-- | morphology-img/README.md | 206 |
1 files changed, 179 insertions, 27 deletions
diff --git a/morphology-img/README.md b/morphology-img/README.md index 2b0ab5e..c9df9e6 100644 --- a/morphology-img/README.md +++ b/morphology-img/README.md @@ -1,24 +1,82 @@ # morphology-img -Convert meta-affine sequences to SVG visualizations using LilyPond. +Convert morphology data structures to SVG visualizations using LilyPond. ## Prerequisites -This library requires **LilyPond** to be installed and available in your system PATH. +This library requires LilyPond to be installed and available in your system PATH. ## Overview The `morphology-img` crate transforms meta-affine sequences from the `morphology` crate into musical notation rendered as SVG images. It uses LilyPond's typesetting engine to generate high-quality visualizations. -## Example +The crate provides two levels of API: +1. **Markup conversion**: Convert sequences to LilyPond markup strings +2. **Complete rendering**: Generate SVG files from sequences -### Basic Usage +## API + +### Rendering Sequences to SVG Files + +The primary API renders sequences directly to SVG files: + +```rust +use morphology::{Sequence, Value}; +use morphology_img::{render_sequences, RenderConfig}; + +// Create sequences +let sequences = vec![ + Sequence::new(vec![ + Value::new(1, 0), + Value::new(-1, 1), + Value::new(-1, 0), + Value::new(0, 0), + ]), + Sequence::new(vec![ + Value::origin(), + Value::new(1, 0), + ]), +]; + +// Configure rendering +let config = RenderConfig::new("output"); + +// Render to SVGs +let svg_paths = render_sequences(&sequences, &config)?; + +// SVG files are created at output/sequence-0.svg, output/sequence-1.svg, etc. +for path in svg_paths { + println!("Created: {}", path.display()); +} +``` + +### RenderConfig + +Configure rendering behavior using the builder pattern: + +```rust +use morphology_img::RenderConfig; + +let config = RenderConfig::new("output") + .keep_temp_files(true) // Keep .ly files for debugging + .lilypond_binary("/usr/local/bin/lilypond") // Custom LilyPond path + .max_batch_size(50); // Process sequences in chunks +``` + +**Methods:** +- `new(output_dir)` - Create config with output directory +- `keep_temp_files(bool)` - Preserve temporary .ly files (default: false) +- `lilypond_binary(path)` - Set path to LilyPond binary (default: "lilypond") +- `max_batch_size(usize)` - Set maximum sequences per batch (default: unlimited) + +### Converting Sequences to Markup + +For lower-level control, convert sequences to LilyPond markup strings: ```rust use morphology::{Sequence, Value}; use morphology_img::sequence_to_markup; -// Create a meta-affine sequence let seq = Sequence::new(vec![ Value::new(1, 0), Value::new(-1, 1), @@ -26,36 +84,96 @@ let seq = Sequence::new(vec![ Value::new(0, 0), ]); -// Convert to LilyPond markup let markup = sequence_to_markup(&seq); -println!("{}", markup); // Output: f'4 f4 e4 b4 +assert_eq!(markup, "f'4 f4 e4 b4"); ``` -## API +### Error Handling -### Converting Sequences to Markup +The `RenderError` enum captures all rendering failures: + +```rust +use morphology_img::{render_sequences, RenderConfig, RenderError}; + +match render_sequences(&sequences, &config) { + Ok(paths) => println!("Rendered {} SVGs", paths.len()), + Err(RenderError::LilyPondNotFound(msg)) => { + eprintln!("LilyPond not installed: {}", msg); + } + Err(RenderError::LilyPondExecution(msg)) => { + eprintln!("LilyPond failed: {}", msg); + } + Err(e) => eprintln!("Error: {}", e), +} +``` + +**Error variants:** +- `LilyPondNotFound` - LilyPond binary not found in PATH +- `LilyPondExecution` - LilyPond failed during rendering +- `Template` - Template processing error +- `FileIO` - File system operation failed +- `InvalidSequence` - Invalid sequence data + +## Batch Processing -The main public API converts sequences directly to LilyPond markup strings: +For large datasets, use batch processing to avoid overwhelming the filesystem: ```rust -use morphology_img::sequence_to_markup; +use morphology_img::RenderConfig; + +// Process 1000 sequences in chunks of 50 +let config = RenderConfig::new("output") + .max_batch_size(50); -let markup = sequence_to_markup(&sequence); +let svg_paths = render_sequences(&sequences, &config)?; ``` +Batch processing creates separate temporary directories for each chunk and invokes LilyPond once per batch for optimal performance. + ## Testing -Run tests with: +Run unit tests: +```bash +cargo test -p morphology-img +``` + +Run integration tests (requires LilyPond): +```bash +cargo test -p morphology-img -- --ignored +``` + +Run all tests: +```bash +cargo test -p morphology-img -- --include-ignored +``` + +## Useful Commands + +Build the crate: +```bash +cargo build -p morphology-img +``` + +Generate documentation: ```bash -cargo test +cargo doc -p morphology-img --open ``` -Some tests require LilyPond to be installed and are marked with `#[ignore]`. To run these: +Check for errors: ```bash -cargo test -- --ignored +cargo check -p morphology-img ``` -## Module Structure +## Architecture + +The crate follows a clean separation of concerns: + +- **Public API**: Only exports `render_sequences`, `sequence_to_markup`, `RenderConfig`, and `RenderError` +- **Hidden implementation**: All LilyPond-specific types (pitches, notes, durations) are internal +- **Input types**: Only accepts types from the `morphology` crate (`Sequence`, `Value`) +- **Output types**: Returns standard library types (`String`, `PathBuf`, `Result`) + +### Module Structure ``` morphology-img/src/ @@ -63,24 +181,58 @@ morphology-img/src/ ├── error.rs // Error types using thiserror ├── note.rs // Integer → LilyPond pitch conversion ├── template.rs // Template handling & substitution -├── file_gen.rs // .ly file generation +├── file_gen.rs // .ly file generation & temp dirs └── render.rs // LilyPond CLI invocation ``` +### Transformation Pipeline + +1. **Sequence → Notes**: Convert `(outer, inner)` pairs to LilyPond pitch names +2. **Notes → Markup**: Serialize notes to space-separated string +3. **Markup → .ly File**: Substitute markup into template +4. **.ly File → SVG**: Invoke LilyPond to render SVG +5. **Cleanup**: Remove temporary files (unless configured to keep) + ## Troubleshooting ### "LilyPond not found" -If you see this error, ensure: -1. LilyPond is installed (see installation instructions above) -2. The `lilypond` command is in your PATH -3. You can run `lilypond --version` from your terminal +Ensure LilyPond is installed and in your PATH: +```bash +lilypond --version +``` + +If installed but not found, specify the full path: +```rust +let config = RenderConfig::new("output") + .lilypond_binary("/usr/local/bin/lilypond"); +``` ### "LilyPond execution failed" -This can happen if: -- The generated .ly file has syntax errors -- LilyPond encountered an internal error -- File permissions prevent LilyPond from writing output +Debug by keeping temporary files: +```rust +let config = RenderConfig::new("output") + .keep_temp_files(true); +``` + +Then inspect the generated .ly files and run LilyPond manually: +```bash +lilypond --svg path/to/sequence-0.ly +``` -Check the error message for specific details. +### Permission errors + +Ensure the output directory is writable: +```bash +mkdir -p output +chmod 755 output +``` + +### Large batch processing + +For very large batches, enable chunking: +```rust +let config = RenderConfig::new("output") + .max_batch_size(100); // Process 100 sequences at a time +``` |