summaryrefslogtreecommitdiff
path: root/morphology-img
diff options
context:
space:
mode:
Diffstat (limited to 'morphology-img')
-rw-r--r--morphology-img/README.md206
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
+```