readme

README.md

@@ -1,5 +1,22 @@
 `thyme` is a tool for creating cross-stitch patterns from PNG files of pixel art.
 
+# Thyme tools
+
+Right now, there are four tools under development:
+
+- `thyme-from-png` takes a PNG file as well as a YAML file that describes the color palette and packs them together into a `.thyme` file.
+- `svg-from-thyme` takes a `.thyme` file and converts it into an SVG file representing the pattern.
+- `svg-from-png` takes the same information as `thyme-from-png` but produces the SVG file directly.
+- `thyme-editor` is a GTK4-based GUI editor to create, view, and edit `.thyme` files.
+
 # Thyme file format
 
-A _thyme_ file is a packed binary file. It always begin with the header `0x7468796d` (i.e. `thym` in hex.)
+A _thyme_ file is a zip file. If unzipped, it will contain the following files:
+
+- `THYME_VERSION`: the file format version, currently `0`. This may eventually be able to foster backwards-compatibility.
+- `dimensions.json`: a JSON array with two numeric values, corresponding to the width and the height.
+- `metadata.json`: a JSON object with free-form keys and string values. This is currently unused, but will be used to include metadata including pattern name, author, modified dates, and so forth.
+- `palette.json`: a JSON array containing objects representing color definitions. Right now, each color has three fields: `name` (a human-readable color name), `symbol` (a single-character string representing a symbol to use in a rendered chart), and `color` (a three-element array representing the RGB representation of a color.) This is subject to change in future versions.
+- `payload.json`: a JSON array whose length should be equal to `width * height`. Each element is either `null` (which means there is no stitch present) or a two-element array containing two numbers: the first number represents the stitch type (right now, full or half) and the second is an index into the `palette` array.
+
+The details of this file format are subject to change.