Shaping and colorwork programs to output knitout files based on input images.
For use in conjunction with a machine-specific knitout backend.
| Installation | Dependencies | Usage | Command-line Prompts | Troubleshooting | Additional Resources |
In the command line, type:
git clone https://github.com/gabrielle-ohlson/knitout-image-processingSee the github documentation on cloning a repository if you need assistance with installation.
The following dependencies will automatically be installed by running the command npm install after the repo has been cloned.
Packages to install with npm (package manager included with node.js):
To install these dependencies, first open your terminal and change into the directory in which you installed the repo (e.g. if you installed it in home/user/code and kept the default repo name, you'd type: cd home/user/code/knitout-image-processing):
cd <whatever-folder-you-installed-the-repo-in/the-repo-name>npm installThe dependenices will appear in a newly created folder called node_modules.
NOTE: ensure that all dependencies have been installed before running the program.
Place the image file (.png or .jpg) that you would like to process in the in-colorwork-images folder.
From your terminal, cd to the parent directory knitout-image-processing (if you have not already done so) and run the command:
npm run knitify
Respond to the prompts as they appear in the terminal.
When the program has finished running, a knitout file will be written to the sub-directory knit-out-files. A visual depiction of the knitting machine instructions will also be written to the parent directory (under the name knit_motif.png).
To then add shaping to the file:
Place an image (.png or .jpg) in the in-shape-images folder (note: the graphic should include a white background and a shape with a completely black fill.)
From your terminal, run the command:
npm run shapeify
and respond to the prompts.
The program will then output a knitout file to the sub-directory knit-out-files.
| Prompt answers: | 1) Pre-load answers | 2) Save answers | 2.a) Save answers as | |||||
| Motif specs: | 3) Colorwork image file | 4) Piece width (stitches) | 5) Piece height (rows) | 6) Machine | ||||
| Image processing: | 7) Color count | 8) Dithering | 9) Palette | |||||
| Knitout extensions: | 10) Stitch number | 11) Speed number | 12) Waste section settings | |||||
| Knitting techniques: | 13) Back style | |||||||
| Stitch patterns: | 14) Stitch patterns | 14.a) Image file | 14.b) Pattern name | 14.c) Specifications | 14.d) Include more? | 14.e) Mapped color | 14.f) Carrier | 14.g) Customizations |
| Carrier assignments: | 15) Cast-on carrier | 16) Waste section carrier | ||||||
| Ribbing: | 17) Rib | 17.a) Top rib | 17.a.i) Carrier | 17.a.ii) Row count | 17.b) Bottom rib | |||
| Save: | 18) Save as |
1. Option to pre-load prompt answers, saved from a prior session. Enter the name of the .json file containing the prompt answers file (which should exist in the prompt-answers folder, or hit the Enter key to skip this prompt.
(press Enter to skip and answer prompts) Filename for pre-loaded prompt answers:e.g. stars.json
2. Option to save the prompt answers for the current session for future re-use, saved from a prior session. Key-in either y (yes) or n (no).
Would you like to save the prompt answers you provide in this session? [y/n]:e.g. y
if y (yes):
- 2.a) Enter a name for the output .json file to write your prompt answer to. The file with be saved to the prompt-answers folder.
Save prompt answers as:e.g. stars.json
3. Enter the name of the image to base the colorwork on (including the extension-- .png or .jpg). The image should exist in the in-colorwork-images folder.
If you are planning to create a piece that only includes a stitch pattern (i.e. no colorwork/motif), hit the Enter key to skip this prompt.
(press Enter to skip if using only stitch pattern) Colorwork image file:e.g. stars.png
4. The image's width (in pixels) will be scaled to the number of stitches you'd like the piece to be (not to exceed the maximum needle count of the machine [e.g. for kniterate, 252, and for swgn2, 540]). Enter a number.
(press Enter to scale stitches according to img dimensions)
How many stitches wide?e.g. 252
5. The same will occur for the image's height (in pixels), in accordance with the row count you specify.
Note that the knitted piece will likely produce a squashed or stretched version of the image, depending on stitch size and yarn thickness. Thus, there is an additional option to input a floating point number to scale the image accordingly.
Also note that if you are using only a stitch pattern and skipped the Colorwork image file prompt, answering this prompt is required.
(Either input an exact row count, press Enter to scale rows according to needle count for true img dimensions, or input a float number for a specific scale.)
How many rows long?e.g. 300
6. Enter the make/model of the machine you will be using.
What model knitting machine will you be using?e.g. kniterate or swgn2
7. The program will reduce the number of colors in the image in accordance with the number you input.
Keep in mind the maximum number of carriers your machine has (e.g. for kniterate, 6).
How many colors would you like to use?e.g. 5
8. This determines how the program processes the image--dithering will create the illusion of a more colorful/detailed motif (with adjacent pixels in different colors optically blended to immitate another color). Opting out of this option will produce colors with hard edges. Key-in either y (yes) or n (no).
Would you like to use dithering? (dithering is recommended for detailed/naturalistic images, but not for graphics/digital artwork.) [y/n]:e.g. y
9. This option is useful for when there are certain colors you would like to prioritize in the image, such as when a color is low in occurrence but high in importance.
If you opt to use a predefined palette, you will be met with the prompt Enter hex-code for color #<n>: for the n-number of colors you indicated that you will be using. Enter the hex-code e.g. #FF0000.
Would you like to use a predefined palette? [y/n]:e.g. n
10. Enter a number to set the stitch size (knitout extension: x-stitch-number) in the main body of the piece. For example, on kniterate machines, there are 16 valid values, with single digit values represented by a number (0 - 9) and double-digit values represented by a letter (A - F, with A being 10 and F being 15). Lower number produce smaller/tighter stitches.
(OPTIONAL: press enter to skip this step) What would you like to set the stitch number as?e.g. 6
11. Enter a number to set the knitting speed for the piece (knitout extension: x-speed-number). Faster speeds are more efficient, but may increase the chances of dropped stitches/broken yarn on less sophisticated machines.
(OPTIONAL: press enter to skip this step) What would you like to set the carriage speed number as? (valid speeds are between <0-600> for kniterate [with 300 as the default] and <0-15> for swgn2 [with 0 denoting the default])e.g. 300 or 0
12. Optionally, you can alter the default knitout-extension settings for the waste section at the beginning of the piece, or just stick with the defaults.
Would you like to change any of the default settings for the waste section? (DEFAULT stitch number: 6, speed number: 400, roller advance: 150, rows: 40) [y/n]:e.g. y
13. Key-in select the style that you'd like the program to produce for the back of the knit.
Note that this prompt will not appear if you are using solely a stitch pattern.
[1] Default
[2] Birdseye
[3] Minimal
[4] Secure
[0] CANCEL
^What style back would you like to use? (note: this doesn't matter if you're using *only* stitch patterns)
=> 'Default' is a freeform option that is similar to Birdseye in performance, but more suitable for pieces containing up to 5 colors.
=> 'Birdseye' is not recommended for pieces that use more than 3 colors due to the build up of extra rows the method creates on the back bed.
=> Alternatively, 'Minimal' creates a reasonably even ratio of front to back rows, resulting in the least amount of build up on the back.
=> 'Secure' is the 'Minimal' option, with additional knits on the side needles for extra security. [1...4 / 0]:e.g. 1
14. Indicate whether or not you'd like to include stitch patterns in the piece (either having the whole piece comprised of stitch patterns, or including sections of stitch patterns within the motif). If yes, you will specify the path to an image that has blobs of color that will be mapped to a specific stitch pattern (overlayed on the rest of the motif).
Note that the image should only include a white background and the colors denoting stitch patterns.
Would you like to include any stitch patterns in your motif? [y/n]:e.g. y
if y (yes):
- 14.a) Enter the name of the stitch pattern graphic file (which should reside in the in-stitch-patterns sub-directory).
(press Enter to skip if using only *one* stitch pattern that *comprises the whole piece*) Stitch pattern image file:e.g. stitch-pattern.png
- 14.b) Key-in select the stitch pattern that you'd like to use in the piece (repeat for however many stitch patterns you'd like to include).
[1] Rib
[2] Bubbles
[3] Seed
[4] Lace
[0] CANCEL
^Select a stitch pattern to use in your motif. [1...4 / 0]:e.g. 1
- 14.c) A number of prompts might follow to give you a chance to indicate specifications for the particular stitch pattern you chose.
(e.g.Which type of rib?)
- 14.d) Option to include another stitch pattern (
y) or to just use the onen.
Note that this prompt (and the rest of the subsequent stitch-pattern-related prompts) will not appear if you are using just one stitch pattern and skipped theStitch pattern image fileprompt.
Would you like to include another stitch pattern? [y/n]:- 14.e) Input the color that the stitch pattern is represented by in the stitch pattern graphic you're using.
Enter the hex-code (or color name) for the color you used to denote the '<your-stitch-pattern>' stitch pattern (e.g. #0000FF or blue):- 14.f) You will be prompted to assign a particular carrier to the given stitch pattern (it can either be one you already used in the piece [all of those will be listed with carrier number and the hex-code you assigned it] or a new carrier, if enough are leftover).
You may choose from the following list of existing carriers (along with the hex-code for the corresponding color), or specify a new carrier (if enough are left over).
Carriers used in the motif thus far:
Carrier 1: #ffffff
Enter the carrier you'd like to use for the '<your-stitch-pattern>' stitch pattern (e.g. 1):- 14.g) Option to add use non-default customizations for the given stitch pattern. If yes (
y), you'll be met with a number of additional prompts specific to the given stitch pattern.
Would you like to add any other customizations for the '<your-stitch-pattern>' stitch pattern? [y/n]:15. Option to indicate a specific carrier you'd like to use for the cast-on. If unspecified (skipped with Enter key), the default carrier will be used for the cast-on, which is whatever color is detected by the program as the background.
(OPTIONAL: press Enter to skip this step and use the default carrier [background color]) Which carrier would you like to use for the cast-on?e.g. 2
16. Option to indicate a specific carrier you'd like to use for the waste section. If unspecified (skipped with Enter key), the default carrier will be used to knit the waste section, which is carrier '1'.
(OPTIONAL: press Enter to skip this step and use the default carrier [1]) Which carrier would you like to use for the waste section?e.g. 3
17. Option to add 1x1 ribbing to the top and/or the bottom of the piece.
Would you like to add rib? [y/n]:e.g. y
if y (yes):
Would you like to add ribbing to the bottom of the piece? [y/n]:if y (yes):
- 17.a.i) Input the carrier to assign to the bottom rib. The hex-code for the carriers used thus far in the piece will be listed as options, and any leftover carriers will also listed in case you want to use a new carrier for the rib.
[1] #hexcode1
[2] #hexcode2
[3] #hexcode3 (...continued for # of colors)
[4] new carrier
[5] new carrier
[6] new carrier
[0] CANCEL
^Which carrier would you like to use for the bottom rib? (the corresponding hex code is listed next to each carrier number) [1...6 / 0]:e.g. 2
How many rows?e.g. 30
- 17.b) Key-in
yorn.
ify(yes), prompts listed about for bottom rib will repeat, this time for top rib.
Would you like to add ribbing to the top of the piece? [y/n]:18. Enter a name for the output knitout file. The file with be saved to the knit-out-files folder.
Save as:e.g. stars.k
| Shape code specs: | 1) Shape | 1.a) Image file | 1.b) Colorwork knitout file | 1.c) Alter the shape code |
| Save: | 2) Save as | |||
| Shaping specs: | 3) Increasing method | 4) Transfer speed |
1. To determine the shaping to apply to the colorwork file you produced, you can choose to either use a custom shape image (represented by a black graphic [.jpg or .png] with a white background) that you've placed in the in-shape-images folder, or to base the shaping off of a pre-made template.
NOTE: option [2] Template is still in progress. Please use only option [1] Custom Shape for now.
[1] Custom Shape
[2] Template
[0] CANCEL
^Would you like to input an image for a custom shape, or use a pre-made template? [1, 2, 0]:e.g. 1
if option [1] Custom Shape is selected:
- 1.a) Input the name of the shape graphic file (which should reside in the in-shape-images folder).
Shape image file:e.g. shape.jpg
- 1.b) Input the name of the colorwork knitout file (which will have been outputted as a rectangular panel by knitify) that you'd like to add shaping to.
NOTE: only use files produced by knitify; they contain information/structure that is necessary for shapeify to successfully parse and process file.
What is the name of the file that you would like to add shaping to?e.g. stars.k
- 1.c) The shape will be processed into a .txt file (titled SHAPE-CODE.txt) with '1' characters represented the shape (black graphic) and '0' characters representing the white space (white background). This file is editable, in case the shape doesn't turn out exactly as you'd like (but it must remain only 1s and 0s, the same number of lines, and the same number of characters in each line). Key-in 'y' when you are done editing the file or if you don't want to make any changes.
WRITING 'SHAPE-CODE.txt' FILE IN WORKING DIRECTORY.
If you would like to edit the shape in the .txt file, please do so now.
Valid characters are: 0 [white space] and 1 [shape]
Are you ready to proceed? [y/n]:e.g. y
2. Enter a name for the output knitout file. The file with be saved to the knit-out-files folder.
Save new file as:e.g. stars-shape.k
if increasing exists in the shape: 3. The program is capable of using three different methods of increasing--the first ('xfer') will increase by transfer stitches on the edge to adjacent empty needles and then knitting twisted stitches (different direction than the other stitches in a given pass) on the new empty needles. The second ('twisted-stitch') will simply knit twisted stitches on adjacent empty needles to increase. The third and final method ('split') will increase by splitting (a technique that involves transferring a loop from one needle to another while knitting a new loop on the first needle).
[1] xfer
[2] twisted-stitch
[3] split
[0] CANCEL
^Which increasing method would you like to use? [1, 2, 3, 0]:e.g. 1
4. Distinct from the knitting speed, a speed for transfer operations can be specified.
What carriage speed would you like to use for transfer operations? (press enter to use default speed, 100.)e.g. 200
If you have any trouble, discover a bug, or want to provide feedback, do not hesitate to use the Issues page.
For example files, see the in-colorwork-images and in-shape-images folders.
Some helpful/relevant resources that you might use or reference alongside this program:
- knitout specifications and examples -- the file format produced by this program; created by CMU's Textiles Lab!
- knitout-kniterate backend github repo and web version -- for converting knitout files to machine code for the Kniterate knitting machine.
- knitout live visualizer -- a super helpful resource for visualizing what a knitout file might look like when knitted (great for debugging and knitout-writing practice).
- knit.work -- a site I worked on with the Textiles Lab that contains a bunch of information/examples/visualizations to help with learning knitout, coding, and machine knitting concepts.