Metadata-Version: 2.4
Name: lovelacemk
Version: 0.1.0
Summary: A package for parsing and converting knitted lace patterns
Project-URL: Homepage, https://github.com/ech0-chambers/lovelace-python
Author: Peter Brookes Chambers
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: pillow
Requires-Dist: pygmentation
Requires-Dist: svg-py
Description-Content-Type: text/markdown

# LoveLaceMK

*A Python package for parsing and converting knitted lace patterns*

This package takes written instructions or charts for hand-knitted lace and converts them to a rendered chart, [AYAB](https://www.ayab-knitting.com/) file, or punchcard for machine knitting.

## Installation

Install with pip:

```{bash}
pip install lovelacemk
```

## Usage

### Input

The input file can be in one of two formats, specified by the `--type` argument: `instructions` (default), or `chart`. 

#### Instructions

A set of written instructions for hand knitting can be parsed, for example `k1, yo, k3, ssk, k1`. The instructions it accepts are intended to match those found in *A Second Treasury of Knitting Patterns* by Barbara Walker, but it is intentionally broad in the formatting it accepts. For example, `sl k2tog psso`, `sl1-k2 tog-psso`, and `slip 1 - knit 2 together - pass slipped stich over` will all be interpreted correctly.

#### Chart

A typed-out chart can also be accepted, such as the one below (for the Ivy Leaf pattern taken from *A Second Treasury of Knitting Patterns*):
```
.o.....\./o.............o\./.....o.
.o....\./oo^oo^oo^oo^oo^oo\./....o.
.o...\./o......o\./o......o\./...o.
.o..\./oo^oo^oo\.../oo^oo^oo\./..o.
.o.\./oo\./o.o\...../o.o\./oo\./.o.
.o\/o....../o\..o.o../o\......o\/o.
..o^o.o\./......o.o......\./o.o^o..
.......o\./.....o.o.....\./o.......
/oo^oo^oo\./....o.o....\./oo^oo^oo\
./o......o\./...o.o...\./o......o\.
../oo^oo^oo\./..o.o..\./oo^oo^oo\..
.../o.o\./oo\./.o.o.\./oo\./o.o\...
.o../o\......o\/o.o\/o....../o\..o.
.o......\./o.o^o...o^o.o\./......o.
```

The following symbols are recognised:

- Yarn over: `o`, `O`, `0`
- Left-leaning decrease (ssk): `\\`
- Right-leaning decrease (k2 tog): `/`
- Double decrease (sl1-k2tog-psso): `^`, `X`, `x`
- Knit: ` ` (space), `.`, `-`

The chart output from `lovelacemk` can also be read as input.

### Output

#### Chart (rendered)

Passing an SVG file (or a file with no extension) to the `--chart` option will cause the lace chart to be rendered as an SVG to this file.

#### Chart (text)

Passing any other file type to the `--chart` option will cause the lace chart to be written in plain text, in the same format as the example [above](#chart).

#### AYAB

The lace pattern can be rendered to an image suitable for use with [AYAB](https://www.ayab-knitting.com/) by passing an image file path to the `--ayab` option. The file will indicate when to knit with the main carriage by including two blank rows; when the lace carriage does not select anything on a left-to-right pass, and does not select anything on the next right-to-left pass, two rows should be knitted with the main carriage.

#### Punchcard

The lace pattern can be written to a text file in the format required for Brenda Bell's [Punchcard Generator](https://brendaabell.com/knittingtools/pcgenerator/), by passing a file path to the `--punchcard` option. No checks are performed to verify that the lace pattern is suitable for a punchcard.

## Example

For an example of the input and output, see the (example)[/example]. The input file was copied directly from *A Second Treasury of Knitting Patterns*, and the output generated with the following two commands:
```bash
python3 -m lovelacemk -i ivy_leaf.txt -c chart.svg -a ayab.png -p punchcard.txt
# once more to generate the text-based chart
python3 -m lovelacemk -i ivy_leaf.txt -c chart.txt
```

When copying and pasting written instructions, be careful that characters are copied directly. Some PDF readers might misinterpret `sl` as `s1` or `si`, and `k1` as `kl` etc.

## Limitations

Since this tool is primarily aimed at machine knitting, there are some limitations:

- All rows must have the same number of stitches
- For chart input, there is no distinction between the types of double decrease (e.g. sl 2 - k1 - psso, sl 1 - k2 tog - psso, or k3 tog). They are all treated as sl 1 - k2 tog - psso, since this is the easiest to replicate on a knitting machine. They are, however, interpreted correctly from written instructions.
- Currently, this package has no concept of purl stitches. For hand knitting instruction input, it assumes that every instruction row is for the right side, with an implied row of plain purls between each instruction row. 
