diff options
| author | jacksonfu14 <jackson@fashionunited.com> | 2025-11-17 06:56:09 +0100 |
|---|---|---|
| committer | Jackson Moore <jacksonmoore@tuta.io> | 2025-11-17 06:56:09 +0100 |
| commit | a20f9a327c4d9e5ac8f42db4e2e9fb29770c3d37 (patch) | |
| tree | 568c2650e8bf015b896f86297176a485b9bb5c08 /morphology-img/README.md | |
| parent | 3077c7af770b055804d5cf48994a4e4cf6d31146 (diff) | |
feature: generate and process ly files
Diffstat (limited to 'morphology-img/README.md')
| -rw-r--r-- | morphology-img/README.md | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/morphology-img/README.md b/morphology-img/README.md new file mode 100644 index 0000000..2b0ab5e --- /dev/null +++ b/morphology-img/README.md @@ -0,0 +1,86 @@ +# morphology-img + +Convert meta-affine sequences 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. + +## Example + +### Basic Usage + +```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), + Value::new(-1, 0), + Value::new(0, 0), +]); + +// Convert to LilyPond markup +let markup = sequence_to_markup(&seq); +println!("{}", markup); // Output: f'4 f4 e4 b4 +``` + +## API + +### Converting Sequences to Markup + +The main public API converts sequences directly to LilyPond markup strings: + +```rust +use morphology_img::sequence_to_markup; + +let markup = sequence_to_markup(&sequence); +``` + +## Testing + +Run tests with: +```bash +cargo test +``` + +Some tests require LilyPond to be installed and are marked with `#[ignore]`. To run these: +```bash +cargo test -- --ignored +``` + +## 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 +└── render.rs // LilyPond CLI invocation +``` + +## 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 + +### "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 + +Check the error message for specific details. |