# morphology-img Convert morphology data structures to SVG visualizations using LilyPond. ## Prerequisites 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. The crate provides two levels of API: 1. **Markup conversion**: Convert sequences to LilyPond markup strings 2. **Complete rendering**: Generate SVG files from sequences ## 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; let seq = Sequence::new(vec![ Value::new(1, 0), Value::new(-1, 1), Value::new(-1, 0), Value::new(0, 0), ]); let markup = sequence_to_markup(&seq); assert_eq!(markup, "f'4 f4 e4 b4"); ``` ### Error Handling 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 For large datasets, use batch processing to avoid overwhelming the filesystem: ```rust use morphology_img::RenderConfig; // Process 1000 sequences in chunks of 50 let config = RenderConfig::new("output") .max_batch_size(50); 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 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 doc -p morphology-img --open ``` Check for errors: ```bash cargo check -p morphology-img ``` ## 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/ ├── lib.rs // Public API, re-exports ├── error.rs // Error types using thiserror ├── note.rs // Integer → LilyPond pitch conversion ├── template.rs // Template handling & substitution ├── 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" 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" 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 ``` ### 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 ```