Updated missing documentation about the Processing sound library in the Readme - Thanks to Heath Iverson for catching this.

README.md

@@ -2,7 +2,7 @@
 
 Scripts and templates for making "filmless", cameraless analog films using free open-source software. 
 
-Building off of the [v2f](https://github.com/sixteenmillimeter/v2f) application for generating film-sized strips of images, this set of tools for building pixel-perfect image sequences for printing and laser cutting into viable 16mm film strips.
+Building off of the [v2f](https://github.com/sixteenmillimeter/v2f) application for generating film-sized strips of images, this is a set of tools for building pixel-perfect image sequences for printing and laser cutting into viable 16mm film strips. Create 16mm films from non-film materials and convert video to strips of film using [Processing](https://processing.org/).
 
 ### [Download](https://github.com/sixteenmillimeter/filmless/archive/master.zip)
 
@@ -12,7 +12,8 @@ Building off of the [v2f](https://github.com/sixteenmillimeter/v2f) application
 2. [Processing sketch for generating pages of film strips](#processing)
 3. [Scripts for exporting video to image sequences](#scripts)
 4. [Calibration](#calibration)
-5. [Installation instructions for dependencies](#dependencies)
+5. [Dependencies & installation instructions](#dependencies)
+6. [Laser cutting tips](#cutting)
 
 <a name="laser"></a>
 ## 1. Laser cutting templates
@@ -23,7 +24,7 @@ The laser cutting templates can be used on their own and without the other compo
 
 The provided [.svg](https://github.com/sixteenmillimeter/filmless/tree/master/svg) and [.dxf](https://github.com/sixteenmillimeter/filmless/tree/master/dxf) files can be opened in whichever application you use to control your laser cutter. With just these files you can cut twelve 33-frame strips of 16mm-sized film from any flat material that you can cut with your laser. Whether or not it will run through a projector depends on the material but at least you can cut it! This has been tried with paper, vellum, acetate and inkjet transparency film.
 
-<img src="docs/vellum.jpeg?raw=true" width="400" height="auto" alt="Vellum closeup" /><img src="docs/acetate.jpeg?raw=true" width="400" height="auto" alt="Acetate closeup" />
+<img src="docs/vellum.jpeg?raw=true" width="400" height="auto" alt="Vellum closeup" /><img src="docs/acetate.jpeg?raw=true" height="368" width="auto" alt="Acetate closeup" />
 
 Using the provided [OpenSCAD](https://www.openscad.org/) file, `scad/16mm_film.scad`, you can generate .dxf or .svg files of your own dimensions. Build strips of any number of frames and generate any number of strips. Just change the variables `FRAMES` and `STRIPS` at the top of the file or use the new Customizer feature in the latest version of OpenSCAD. The default values are `FRAMES = 33` and `STRIPS = 12` which fits into a US Letter sized piece of paper (or inkjet transparency film).
 
@@ -34,11 +35,13 @@ For more advanced tweaks, you can change the `PITCH` variable from "long" to "sh
 The "pitch" of the film refers to the distance between the perforations and it varies between camera stocks and projection stocks. If you plan on contact printing your results from this process, it may make sense to you to use "short" pitch (7.605mm). If you plan on scanning, optical printing or projecting your results, "long" pitch (7.62mm) may work best.
 
 <a name="processing"></a>
-## 2. A Processing sketch for generating pages of film strips
+## 2. Processing sketch for generating pages of film strips
+
+This Processing sketch will create a printable page of 16mm-sized film strips from an image sequence. Generate an image sequence from a video file using the [convert.sh script](#scripts) or generate your own using your application of choice. Create standard strips of standard 16mm or Super16-sized images on single or double perforated film optionally containing a generated optical soundtrack.
 
 ![Video converted to film strips](docs/video.jpeg)
 
-If you have installed Processing and the required libraries ([read below](#ffmpeg)) you can use this sketch to generate pages containing strips of 16mm-sized images from image sequences. Using the default settings, this will build a page of 12 strips, each 33 frames long that will comfortably fit on a letter-sized piece of 8.5" x 11" sheet of inkjet transparency film.
+If you have installed Processing and the required libraries ([read below](#ffmpeg)) you can use this sketch to generate pages containing strips of 16mm-sized images from image sequences. Using the default settings, this will build a page of 12 strips, each 33 frames long, that will comfortably fit on a letter-sized 8.5" x 11" sheet of inkjet transparency film.
 
 ![Video with sound converted to film strips](docs/video2.jpeg?raw=true)
 
@@ -67,21 +70,23 @@ To use the export script, first navigate to the `filmless` folder. If you downlo
 cd /path/to/filmless
 ```
 
-Then, to run the export script simply pass in a path to your video as the first and only argument. In this example "/path/to/my/video.mov" will actually be a path to the video you wish you turn into an image sequence.
+Then, to run the export script, simply pass in a path to your video as the first and only argument. In this example "/path/to/my/video.mov" will actually be a path to the video you wish you turn into an image sequence.
 
 ```bash
 sh scripts/export.sh /path/to/my/video.mov
 ```
 
-This will export the video in a .png sequence to a folder on your Desktop in a folder named "frames". This is the default directory that the `filmless_processing.pde` sketch will look for an image sequence. If your video contained any audio, it will be exported to a mono file named "audio.wav" in the "audio" folder now on your desktop. Otherwise you may see an error message in your terminal telling you that it couldn't find a stream. Not to worry.
+Tip for macOS Terminal users: You can get an absolute path to any file by simply dragging it into Terminal. Type "sh scripts/export " including the space at the end and then drag your video into Terminal and hit enter. Voilà.
+
+This will export the video in a *high quality* .png sequence to a folder on your Desktop in a folder named "frames". This is the default directory that the `filmless_processing.pde` sketch will look for an image sequence. If your video contained any audio, it will be exported to a mono file named "audio.wav" in the "audio" folder now on your desktop. Otherwise you may see an error message in your terminal telling you that it couldn't find a stream. Not to worry.
 
 You don't need to use this script to export your video to image sequences. You can use the application of choice to create your image sequences for the Processing sketch. This script simply lets you do that from the command line without opening up an NLE or media export program. 
 
-You can alternately generate image sequences with other Processing sketches, thereby having a completely cameraless and **cough** filmless process for creating 16mm analog movies.
+You can alternately generate image sequences with other Processing sketches, thereby having a completely cameraless and ***cough*** filmless process for creating 16mm analog movies.
 
-<img src="docs/generative2.jpeg" alt="Generative example from Processing sketch" width="400" height="auto" /><img src="docs/gan.jpeg" alt="Example from a GAN" width="400" height="auto" />
+<img src="docs/generative2.jpeg" alt="Generative example from Processing sketch" width="400" height="auto" /><img src="docs/gan.jpeg" alt="Example from a GAN" height="398" width="auto" />
 
-Note: Processing can only read .tif files produced by the application itself, so unless you are using an image sequence generated by Processing save your files as .png or .jpeg. This
+Note: Processing can only read .tif files produced by the application itself, so unless you are using an image sequence generated by Processing save your files as .png or .jpeg.
 
 There are a few parameters to tweak in the script for best results.
 
@@ -95,30 +100,30 @@ Changing "WITH_SOUND" to any value other than true will tell the script to not t
 AUDIO_RATE=10368
 ```
 
-If you plan on using audio, this is important to pay attention to. The maximum sample rate of your audio is limited by the resolution of your printer. The maximum number of lines that can be used to describe the audio in a printed soundtrack can be determined by a relatively simple formula.
+If you plan on using audio, "AUDIO_RATE" important to pay attention to. The maximum sample rate of your audio is determined by the maximum resolution of your printer. The maximum number of lines that can be used to describe the audio in a printed soundtrack can be determined by a relatively simple formula.
 
 ```
 AUDIO_RATE = ONE SECOND OF FRAMES * FILM PITCH * (DPI / MM PER INCH)
 ```
 
-Using long pitch film measurements and 1440 as our DPI. An inch is equal to 25.4mm. There are 24 frames in one second of 16mm film.
+Using long pitch film measurements and 1440 as our DPI, an inch being equal to 25.4mm and there being 24 frames in one second of 16mm film...
 
 ```
-10368 = 24 * 7.62 * (1440 / 25.4)
+24 * 7.62 * (1440 / 25.4) = 10368
 
 ```
 
-Reducing the sample rate to the maximum that this process can produce serves two purposes: it gives you the best quality soundtrack in the minimum amount of processing time and it allows you to preview some of the distortion that you will hear in your printed soundtrack. Higher frequencies are impossible and you can mix accordingly.
+Reducing the sample rate to the maximum that this process can produce serves two purposes: it gives you the best quality soundtrack in the minimum amount of processing time and it allows you to preview some of the distortion that you will hear in your printed soundtrack. Higher frequencies are impossible to reproduce and you can mix accordingly.
 
 The value you can use for the soundtrack sample rate will be output in both the `filmless_processing.pde` and `filmless_calibration.pde` sketches when you set your parameters, including your target DPI. [Read more about the calibration sketch](#calibration) below.
 
 ### calibration.sh
 
-The default DPI of an image created by Processing is 72. Meanwhile, your printer is likely capable of printing at a much higher density. 600, 1200, 2880 or higher. When creating images meant for 1200 DPI but creating one that says it's only 72 DPI will create a nightmare when trying to print at "actual" size. 
+The default DPI of an image created by Processing is 72. Meanwhile, your printer is likely capable of printing at a much higher density. 600, 1200, 2880 and beyond. When creating images meant for a 1200 DPI printer but creating one that says it's only 72 DPI will create a headache when trying to print at "actual" size. 
 
 Use this script to change your calibration .png files to the same DPI used to generate them. Then, when printing, you'll be able to tell your printer to scale the image to 100% rather than some fractional percentage (`1200 / 72` for example).
 
-This script requires [ImageMagick](https://imagemagick.org/index.php) and will convert the images output by the `filmless_calibration.pde` sketch to the correct DPI for accurate scale printing. Make sure to set the `DPI` variable of the script to the same value used in the sketch. Running it will convert any .png in the "filmless_calibration" directory to the desired DPI.
+This script requires [ImageMagick](https://imagemagick.org/index.php) and will convert the images output by the `filmless_calibration.pde` sketch to the correct DPI for accurate scale printing. Make sure to set the `DPI` variable of the script to the same value used in the sketch. Running it will convert any .tif in the "filmless_calibration" directory to a .png with the desired DPI. This allows for massive reduction in file size with a lossless conversion.
 
 ```bash
 sh scripts/calibration.sh
@@ -128,12 +133,14 @@ sh scripts/calibration.sh
 
 Similar to the calibration script, this will convert your output .tif files from `filmless_processing.pde` to the correct DPI. Also set the `DPI` variable in this script to the one used in your Processing sketch. By default, this looks for files named `page_*.tif` on your Desktop.
 
+Unlike the calibration script, this does not convert your image to .png but maintains the TIFF format.
+
 <a name="calibration"></a>
 #### 4. Calibration
 
 The purpose of the calibration sketch `filmless_calibration.pde` is to generate a page to calibrate between your printer and laser cutter. The page it creates is easy on your ink cartridge while determine if there is any stretch or squish happening to your generated pages of film strips before you commit to printing them out for cutting.
 
-You should re-perform this step when you change printers or any significant print settings that affect the quality or media you're printing onto.
+You should re-perform this step when you change printers, laser cutters or make any significant adjustments to your printer settings that affect the quality or media you're printing onto. This sketch was created because after performing many repeatable tests with a working progress, an adjustment to a media quality value in a Epson printer settings dialog caused pages to start printing with a 2-3mm stretch along the height. This processes effectively mitigated that distortion.
 
 The calibration sketch should be set up with the same variables you intend to use to generate your pages of film strips.
 
@@ -149,7 +156,7 @@ float SAFE_H = .5;
 
 This sketch produces an image that is the same size as one page produced by `filmless_processing.pde` that contains four 10mm x 10mm squares on the outer corners of the image area and contains two 100mm rulers along both the horizontal and vertical axises.
 
-![Output of processing_calibration.pde](docs/calibration.png?raw=true "Output of processing_calibration.pde")
+![Output of processing_calibration.pde](docs/filmless_calibration.png?raw=true "Output of processing_calibration.pde")
 
 The "magic" variables determine the overall stretch or squash of the entire page. When set to 1, the resulting page will not be changed. When set above 1 the page has its height or width stretched and below 1 will cause it to be squashed.
 
@@ -175,11 +182,13 @@ CALIBRATION H (MM): 251.45999
 SOUNDTRACK SAMPLE RATE: 10368
 ```
 
+Note: The "CALIBRATION W (MM)" and "CALIBRATION H (MM)" values refer to the total distance from corner to corner of the squares. These value will be printed on your calibration page and can be used in place of the 100mm rulers. If the top two squares measure 194mm across instead of 192mm, your `MAGIC_W_CORRECTION` fraction would be `192.0 / 194.0`.
+
 <a name="dependencies"></a>
-## Dependencies
+## 5. Dependencies
 
 * [Processing](https://processing.org/) - [[Download](https://processing.org/download/)]
-* [Sound library for Processing](https://processing.org/reference/libraries/sound/index.html) - [[Installation instructions]()]
+* [Sound library for Processing](https://processing.org/reference/libraries/sound/index.html) - [[Download if not installed by default](https://github.com/processing/processing-sound)]
 * [SoundtrackOptical library for Processing](https://github.com/sixteenmillimeter/SoundtrackOptical)
 * (optional) [ffmpeg](https://www.ffmpeg.org/) - [[Download](https://www.ffmpeg.org/download.html)] or [[Installation instructions](#ffmpeg)]
 * (optional) [OpenSCAD](https://www.openscad.org/) - [[Download](https://www.openscad.org/downloads.html)]
@@ -220,6 +229,8 @@ yum install ffmpeg imagemagick
 
 The scripts are tested on macOS and Linux, but can be converted to work with Windows operating systems with few edits. Check the install links above for the Windows executables for ffmpeg and ImageMagick. Happy to accept pull requests for updates to the bash scripts to support all operating systems.
 
+## 6. Laser cutting tips
+
 ------
 
 <a name="variables"></a>

scripts/calibration.sh

@@ -17,7 +17,7 @@ for f in $CALIBRATION_FILES
 do
 	name=$(basename "$f" .tif)
 	#echo $name
-	echo "Converting $f -> ../filmless_calibration/${name}.png..."
+	echo "Converting $f -> ../filmless_calibration/${name}.png @ ${DPI}dpi..."
 	convert $f -units PixelsPerInch -density $DPI "../filmless_calibration/${name}.png"
 	rm $f
 done

scripts/pages.sh

@@ -10,13 +10,11 @@ DPI=1440
 #Location of generated pages
 PAGE_FILES="~/Desktop/page_*.tif"
 
-echo "Changing calibration files to ${DPI}dpi..."
+echo "Changing exported page files to ${DPI}dpi..."
 
 for f in $PAGE_FILES
 do
 	name=$(basename "$f" .tif)
-	#echo $name
+	echo "Converting ${f} to ~/Desktop/${name}.png @ ${DPI}dpi..."
-	echo "Converting $f..."
+	convert $f -units PixelsPerInch -density $DPI "~/Desktop/${name}.png"
-	mogrify $f -units PixelsPerInch -density $DPI
-	rm $f
 done