Basic analysis of Autokern done.

README.md

@@ -1,4 +1,4 @@
-kernall: Kerning and letterspacing research
+Kerning and letterspacing research
 ===========================================
 
 This repository hosts material that I am collecting about various

typefacet-arguments.md

@@ -1,7 +1,5 @@
-
-
-Arguments
----------
+Autokern Arguments
+==================
 
 ### Basic operation
 
@@ -18,28 +16,35 @@ file to create.
 `--min-distance-ems` Sets a minimum allowable distance between the
 contours of adjacent glyphs.
 
-`--max-distance-ems` Sets the maximum distance allowed between any two glyphs. 
+`--max-distance-ems` Sets the maximum distance allowed between any two
+glyphs in the typeface. 
 
+`--intrusion-tolerance-ems` Sets the maximum amount to which a pair of
+kerned glyphs can "intrude" into the spacing between them.  In
+practice, this parameter corresponds roughly to the horizontal extent
+of a pair of serifs.
 
-`--intrusion-tolerance-ems` Sets the maximum amount to which glyphs can "intrude" into the spacing between them. 
-
-`--max-x-extrema-overlap-ems`
+`--max-x-extrema-overlap-ems` Sets the maximum amount to which glyphs' *extrema*
+are allowed to overlap once kerned.  This does not allow contours to
+intersect; rather, it is the maximum amount by which (for example) the
+extrema of the glyphs in "VA" overlap.
 
 `--precision-ems` Sets the numeric precision to use for calculations.
 Smaller values are more CPU intensive.
 
 
 ### Glyph selection
 
-`--sample-texts` "*AbCdEfXyZ*" Sets the 
+`--sample-texts` "*AbCdEfXyZ*" Sets the glyphs to be examined.
 
-`--kern-samples-only`
+`--kern-samples-only` Restricts output to kerning values and not side bearings.
 
-`--glyph-pairs-to-kern`
+`--glyph-pairs-to-kern` *A V T o A v* Sets pairs of glyphs to be kerned.
 
-`--glyphs-to-kern`
+`--glyphs-to-kern` "*AaBbCcDd*" Sets a list of glyphs to be kerned;
+all combinations will be processed.
 
-`--glyphs-to-ignore`
+`--glyphs-to-ignore` "*QqXxYyZz*" Sets a list of glyphs to skip.
 
 
 ### Additional tunable settings
@@ -56,7 +61,10 @@ values less than N.
 `--max-kerning-pairs` *N* Tells Autokern to only output the N largest
 kerning values and discard the rest. 
 
-`--x-extrema-overlap-scaling`
+`--x-extrema-overlap-scaling` *N* Sets a multiplier to be applied to
+the `x-extrema-overlap-ems` values.  Can be used to in combination
+with the glyph-selection arguments to scale the results for different
+classes of glyphs (e.g., miniscules and majuscules).
 
 `--tracking-ems` *N* (mentioned in the documentation as `--tracking`)
 Tells Autokern to add a constant N value to all kerning values.
@@ -68,17 +76,29 @@ ascender.
 
 ### Glyph selection by category
 
-`--glyph-categories-to-ignore`
+These settings allow the user to alter the Autokern run according to classes of
+glyph.  Each class must be specified by a [Unicode
+category](http://charlesmchen.github.io/typefacet/topics/autokern/glyph_categories.html).
+For example, `Po` for "Punctuation, other" or "Lu" for "Letter,
+uppercase."  Each of these arguments can take a space-separated list
+of classes (followed, where necessary by numercic values).
+
+`--glyph-categories-to-ignore` *Cc* *Cd* *[…]* Sets glyph classes to skip in this run.
 
-`--max-x-extrema-overlap-ems-per-category`
+`--max-x-extrema-overlap-ems-per-category` *Cc* *N* *Cd* *M*  *[…]* Sets the
+`max-x-extrema-overlap-ems` parameter for a class or list of glyph classes.
 
-`--max-distance-ems-per-category`
+`--max-distance-ems-per-category` *Cc* *N* *Cd* *M*  *[…]* Sets the
+`max-distance-ems` parameter for a class or list of glyph classes.
 
-`--min-distance-ems-per-category`
+`--min-distance-ems-per-category` *Cc* *N* *Cd* *M*  *[…]* Sets the
+`max-x-distance-ems` parameter for a class or list of glyph classes.
 
-`--intrusion-tolerance-ems-per-category`
+`--intrusion-tolerance-ems-per-category` *Cc* *N* *Cd* *M*  *[…]* Sets the
+`intrusion-tolerance-ems` parameter for a class or list of glyph classes.
 
-`--tracking-ems-per-category`
+`--tracking-ems-per-category` *Cc* *N* *Cd* *M*  *[…]* Sets the
+`tracking-ems` parameter for a class or list of glyph classes.
 
 
 ### Additional logging options

typefacet.md

@@ -4,8 +4,7 @@ TypeFacet Autokern
 Charles M. Chen's [Autokern](http://charlesmchen.github.io/typefacet/topics/autokern/index.html) is a command-line Python tool released as
 part of Chen's *TypeFacet* software collection.  It reads in UFO font
 files and takes a set of user-supplied arguments, then outputs a
-modified UFO file with adjusted side-bearings and, optionally, kerning
-values.
+modified UFO file with kerning values and, optionally, adjusted side-bearings.
 
 Usage
 -----
@@ -24,7 +23,7 @@ step, one can inspect the output UFO file to note which glyph pairs
 may be problematic.
 
 Second, one runs Autokern again (on the same input UFO) to set the
-`min-distance-ems1` parameter to some non-zero value.  Selecting the
+`min-distance-ems` parameter to some non-zero value.  Selecting the
 appropriate value is up to the user based on trial runs and inspecting
 the results.  The parameter is meant to reflect the minimum spacing
 between two glyphs that come as close as possible to touching.  For
@@ -84,29 +83,87 @@ glyph: one pair by "inflating" each glyph a distance of
 
 The `min-distance` profiles are moved together until they touch, as are
 the `max-distance` profiles.  This determines the "minimum advance"
-and "maximum advance" for the kerning pair.
+and "maximum advance" values for the kerning pair.
 
 Next, the `max-distance` profiles are adjusted to determine the
-"intruding advance", which is distance adjustment that results in the
+"intruding advance", which is the distance adjustment that results in the
 most equally balanced "intrusion" amount for the two glyphs—that
-is, each glyph intrudes by a close-to-equal amount, within the
-intrusion tolerance parameter.  The intrusion advance is found by
-binary search on the interval [0, int(ceiling(2.0 * max(pair_intrusion_tolerance, pair_max_distance)))].
+is, each glyph intrudes by a close-to-equal amount, without exceeding the
+intrusion tolerance parameter.
+
+The intruding advance is found via 
+binary search on the interval [0, int(ceiling(2.0 *
+max(pair_intrusion_tolerance, pair_max_distance)))].  At each step,
+the algorithm takes the horizontal distance between the facade profiles at
+several y-axis values, looking for collisions between the profiles.
+If a collision is detected, the next iteration moves to the "far" side
+of the remaining search interval.
 
 The final kern is determined by summing the intruding advance (or the
-minimum advance parameter, if it is greater than the intruding
-advance), any pair-tracking value provided, the
+"minimum advance" value, if that is greater than the intruding
+advance), any `tracking-ems` value provided as a parameter, the
 `x-extrema-overlap-scaling` parameter, and the greater of the
-`x-extrema-overlap` or `max-x-extrema-overlap` parameters.
+`x-extrema-overlap` and `max-x-extrema-overlap` parameters.
 
 The facade profiles used in the collision-detection and intrusion
 steps are of reduced precision (in comparion to the font's internal
 point system); the precision used is derived from the `precision-ems`
 parameter. 
 
+The algorithm can also be tweaked with the
+`ignore-x-extrema-overlap-outside-ascender` parameter, which
+limits the spacing-adjustment process to measurements within the x-height.
+
 Analysis
 --------
 
 Bluntly speaking, Autokern makes "common sense" kerning calculations
 based on what it assumes to be a properly letterspaced input font.
 Which is to say that it attempts to make unobtrusive changes.
+
+As far as the critical "intruding advance" step is concerned, the
+algorithm measures the horizontal distance between the two glyphs at a
+number of y-axis sample heights, but the samples also take three
+specific conditions into account:
+
+- Large contiguous gaps at the top of bottom are discarded; this
+  removes the effect (for example) of the left ascender in the pair
+  "hh".
+
+- Large gaps in the middle of the height samples are de-emphasized by
+  replacing them with the maximum protrusion value.  This removes
+  undue impact from the open bowl in "c".
+
+- Sample rows that exist solely because of the glyph-inflation process
+  are discarded.  This essentially chops the profiles off at the
+  original glyph's vertical extrema.
+
+Together with the `pair-intrusion-tolerance` parameter, these conditions
+restrict the intrusion-advance search to commonly accepted rules about
+Latin typefaces.  That said, more specific rules might produce more
+pleasing results.  As implemented, the rules are somewhat ad-hoc.  The
+amount of "large contiguous gap" that triggers the "hh condition is
+hard-coded to `pair_max_distance` * 0.5.  Depending on the typeface,
+that might trigger false positives for (say) "L" or"T".
+
+Several of the other conditions in the intruding-advance step are
+similarly hard-coded.  It is an open question whether these metrics
+produce the best results.
+
+At a higher level, the glyph-inflation process used to create the
+facade profiles might bear closer examination as well.  It "inflates"
+glyphs by a fixed amount, both horizontally and vertically, in an
+attempt to define a "bubble" into which adjacent glyphs should not
+intrude.  But the fixed-radius inflation may not correspond well to
+how glyphs (particularly those with dense or complex contours) behave.
+
+Finally, the usage of the Autokern tool itself requires the user to
+employ multiple, manual steps.  Much of the functionality could be
+broken out into a reusable library to automate some of the
+parameter-determining stages or to work interactively.
+
+The manual determination of the parameters (particularly
+`max-x-extrema-overlap-ems` and `intrusion-tolerance-ems`) is a
+crucial input to the final results.  In a sense, since these
+parameters are not automatically determined for a given input
+typeface, the final output can only be considered partially automated.