README for ppedit

Raph Levien
4 May 2007

ppedit is my prototype application for editing curves using my
curvature-continuous spirals. While I have used this code to draw many
font outlines, it is very rough around the edges, and is far from a
polished tool.


== License and patent grant ==

Update as of 10 May 2019 (the previous license was GNU General Public License
with a patent grant):

The code in this repository is licensed under the terms of the [Apache-2](../LICENSE-APACHE) or
[MIT](../LICENSE-MIT) license, at your choice.

The ideas in this repository are free for all to implement. Previously there
were patents and a provisional patent application, but those are hereby passed
into the public domain.

== Building ==

The main build supported right now is the Gtk2/cairo one. There's also
a Mac build and a Gtk1 one, but those aren't guaranteed to work.

1. Make sure you've got ../x3/ in a directory parallel to ppedit. If
   you've unpacked from a tarball, this should be the case already.
   From darcs, use: darcs get http://levien.com/garden/x3

2. make

3. The binary is ppedit

== Using ==

The numeric keys 1-6 select the mode. 1 is selection, 2-6 select
different point modes:

2: Add G4-continuous curve point
3: Add corner point
4: Add left-facing one-way point
5: Add right-facing one-way point
6: Add G2-continuous curve point

Note: Dave Crossland has a set of alternate keybindings which are
probably faster.

== Plate files ==

Ctrl-S saves a plate file in a file of the name 'plate'. Additionally,
a plate file can be given as a command line argument. The file uses
simple S-expressions, with a one-character code for each point, then
the X and Y coordinates - 0,0 is top left.

Here's the cap U from Inconsolata, for example:

(plate
  (v 68 78)
  (v 159 78)
  (o 158 92)
  ([ 148 115)
  (] 148 552)
  (o 298 744)
  ([ 459 549)
  (v 459 78)
  (v 536 78)
  (] 536 547)
  (o 295 813)
  ([ 68 551)
  (z)
)

v: corner
o: g4
c: g2
[: left-facing one-way
]: right-facing one-way

== Conversion to PostScript ==

Ctrl-P converts to PostScript, saving '/tmp/foo.ps'. Other utilities
can convert that representation into FontForge, and also optimize the
Beziers.

== Stability ==

The spline solver in this release is _not_ numerically robust. When
you start drawing random points, you'll quickly run into divergence.
However, "sensible" plates based on real fonts usually converge. Some
tips:

1. Huge changes of angle are likely to diverge.

2. For the first two or three points, G4 points are likelier to
   converge than G2's. For longer segments, G2 is more likely.

3. Start on a curve point.

A more numerically robust approach is in the works.