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