1# collidoscope - brute force detection of glyph collisions 2 3`collidoscope` reports on situations where paths overlap in a shaped 4piece of text. For example, the sequence "ؼجب" might cause a collision like so: 5 6![](sample-collision.png) 7 8This software tries every combination of glyphs within a specified Unicode range and up to a specified length of string and outputs a report of all situations where the glyphs collide. It has a number of collision tests: 9 10* Paths in non-adjacent glyphs are never allowed to collide. 11* If the *cursive* test is turned on, then paths with a cursive attachment anchor are allowed to overlap with paths in an adjacent glyph which also contain a cursive attachment anchor, but are *not* allowed to overlap with a path *without* a cursive attachment anchor. 12* If the *area* test is turned on, then paths in adjacent glyphs may collide so long as the area of overlap does not exceed a given percentage of the smallest path's area. i.e. if the area percentage is set to 25%, then two strokes may *connect*, because the overlap is likely to be quite small compared to the size of the paths involved. But if a stroke significantly overlaps a nukta, it will be reported as a collision. (Of course, this will not detect strokes which merely graze a nukta.) 13 14Depending on the length of the string and the number of glyphs tested, this may take a *very* long time. 15 16## Command Line Usage 17 18To use it: 19 20 python3 -m collidoscope -r 0620-064A yourfont.otf 21 22This creates a collision report on `report.html` for all sequences of three characters within the range 0x620 to 0x64A. 23 24 python3 -m collidoscope -r 0620-064A,0679-06D3 -area 10 yourfont.otf 25 26This creates a collision report on `report.html` for all sequences of three characters within the range 0x620 to 0x64A and also 0x679 to 0x6D3, and turns on the area test at a tolerance of 10% of the area of the smallest path involved in collision. 27 28 python3 -m collidoscope -c 5 --cursive yourfont.otf 29 30This tests for non-adjacent glyphs and collisions not involving cursive connection for *all combinations of glyphs in your font* with a five-character string. This may take a number of years to compute. 31 32 python3 -m collidoscope -c 2 -r 0620-064A --area 5 yourfont.otf 33 34This just runs an area test for two-character sequences across the basic Arabic range. 35 36## Library Usage 37 38```python 39class Collidoscope() 40``` 41 42Detect collisions between font glyphs 43 44<a name="collidoscope.Collidoscope.__init__"></a> 45#### \_\_init\_\_ 46 47```python 48 | __init__(fontfilename, rules, direction="LTR", ttFont=None) 49``` 50 51Create a collision detector. 52 53The rules dictionary may contain the following entries: 54 55* faraway (boolean): If true, non-adjacent base glyphs are tested for 56overlap. Mark glyphs are ignored. All collisions are reported. 57* marks (boolean): If true, collisions between all pairs of marks in 58the string are reported. 59* bases (boolean): If *false*, collisions between all pairs of bases in 60the string are *ignored*. 61* cursive (boolean): If true, adjacent glyphs are tested for overlap. 62Paths containing cursive anchors are allowed to overlap, but 63collisions between other paths are reported. 64* area (float): If provided, adjacent glyphs are tested for overlap. 65Collisions are reported if the intersection area is greater than 66the given proportion of the smallest path. (i.e. where cursive 67connection anchors are not used in an Arabic font, you may wish 68to ignore collisions if the overlaid area is less than 5% of the 69smallest path, because this is likely to be the connection point 70between the glyphs. But collisions affecting more than 5% of the 71glyph will be reported.) 72 73**Arguments**: 74 75- `fontfilename` - file name of font. 76- `rules` - dictionary of collision rules. 77- `ttFont` - fontTools object (loaded from file if not given). 78- `direction` - "LTR" or "RTL" 79 80<a name="collidoscope.Collidoscope.get_glyphs"></a> 81#### get\_glyphs 82 83```python 84 | get_glyphs(text) 85``` 86 87Returns an list of dictionaries representing a shaped string. 88 89This is the first step in collision detection; the dictionaries 90returned can be fed to ``draw_overlaps`` and ``has_collisions``. 91 92<a name="collidoscope.Collidoscope.draw_overlaps"></a> 93#### draw\_overlaps 94 95```python 96 | draw_overlaps(glyphs, collisions, attribs="") 97``` 98 99Return an SVG string displaying the collisions. 100 101**Arguments**: 102 103- `glyphs` - A list of glyphs dictionaries. 104- `collisions` - A list of Collision objects. 105- `attribs` - String of attributes added to SVG header. 106 107<a name="collidoscope.Collidoscope.has_collisions"></a> 108#### has\_collisions 109 110```python 111 | has_collisions(glyphs_in) 112``` 113 114Run the collision detection algorithm according to the rules provided. 115 116Note that this does not find *all* overlaps, but returns as soon 117as some collisions are found. 118 119**Arguments**: 120 121- `glyphs` - A list of glyph dictionaries returned by ``get_glyphs``. 122 123- `Returns` - A list of Collision objects. 124 125 126## Requirements 127 128This requires some Python modules to be installed. You can install them like so: 129 130 pip3 install -r example-requirements.txt 131