summaryrefslogtreecommitdiff
path: root/morphology-img/README.md
diff options
context:
space:
mode:
authorjacksonfu14 <jackson@fashionunited.com>2025-11-17 06:56:09 +0100
committerJackson Moore <jacksonmoore@tuta.io>2025-11-17 06:56:09 +0100
commita20f9a327c4d9e5ac8f42db4e2e9fb29770c3d37 (patch)
tree568c2650e8bf015b896f86297176a485b9bb5c08 /morphology-img/README.md
parent3077c7af770b055804d5cf48994a4e4cf6d31146 (diff)
feature: generate and process ly files
Diffstat (limited to 'morphology-img/README.md')
-rw-r--r--morphology-img/README.md86
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.