# collidoscope - brute force detection of glyph collisions
`collidoscope` reports on situations where paths overlap in a shaped
piece of text. For example, the sequence "ؼجب" might cause a collision like so:
This 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:
* Paths in non-adjacent glyphs are never allowed to collide.
* 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.
* 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.)
Depending on the length of the string and the number of glyphs tested, this may take a *very* long time.
## Command Line Usage
To use it:
python3 -m collidoscope -r 0620-064A yourfont.otf
This creates a collision report on `report.html` for all sequences of three characters within the range 0x620 to 0x64A.
python3 -m collidoscope -r 0620-064A,0679-06D3 -area 10 yourfont.otf
This 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.
python3 -m collidoscope -c 5 --cursive yourfont.otf
This 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.
python3 -m collidoscope -c 2 -r 0620-064A --area 5 yourfont.otf
This just runs an area test for two-character sequences across the basic Arabic range.
## Library Usage
```python
class Collidoscope()
```
Detect collisions between font glyphs
<a name="collidoscope.Collidoscope.__init__"></a>
#### \_\_init\_\_
```python
| __init__(fontfilename, rules, direction="LTR", ttFont=None)
```
Create a collision detector.
The rules dictionary may contain the following entries:
* faraway (boolean): If true, non-adjacent base glyphs are tested for
overlap. Mark glyphs are ignored. All collisions are reported.
* marks (boolean): If true, collisions between all pairs of marks in
the string are reported.
* bases (boolean): If *false*, collisions between all pairs of bases in
the string are *ignored*.
* cursive (boolean): If true, adjacent glyphs are tested for overlap.
Paths containing cursive anchors are allowed to overlap, but
collisions between other paths are reported.
* area (float): If provided, adjacent glyphs are tested for overlap.
Collisions are reported if the intersection area is greater than
the given proportion of the smallest path. (i.e. where cursive
connection anchors are not used in an Arabic font, you may wish
to ignore collisions if the overlaid area is less than 5% of the
smallest path, because this is likely to be the connection point
between the glyphs. But collisions affecting more than 5% of the
glyph will be reported.)
**Arguments**:
- `fontfilename` - file name of font.
- `rules` - dictionary of collision rules.
- `ttFont` - fontTools object (loaded from file if not given).
- `direction` - "LTR" or "RTL"
<a name="collidoscope.Collidoscope.get_glyphs"></a>
#### get\_glyphs
```python
| get_glyphs(text)
```
Returns an list of dictionaries representing a shaped string.
This is the first step in collision detection; the dictionaries
returned can be fed to ``draw_overlaps`` and ``has_collisions``.
<a name="collidoscope.Collidoscope.draw_overlaps"></a>
#### draw\_overlaps
```python
| draw_overlaps(glyphs, collisions, attribs="")
```
Return an SVG string displaying the collisions.
**Arguments**:
- `glyphs` - A list of glyphs dictionaries.
- `collisions` - A list of Collision objects.
- `attribs` - String of attributes added to SVG header.
<a name="collidoscope.Collidoscope.has_collisions"></a>
#### has\_collisions
```python
| has_collisions(glyphs_in)
```
Run the collision detection algorithm according to the rules provided.
Note that this does not find *all* overlaps, but returns as soon
as some collisions are found.
**Arguments**:
- `glyphs` - A list of glyph dictionaries returned by ``get_glyphs``.
- `Returns` - A list of Collision objects.
## Requirements
This requires some Python modules to be installed. You can install them like so:
pip3 install -r example-requirements.txt
Raw data
{
"_id": null,
"home_page": "https://github.com/simoncozens/collidoscope",
"name": "collidoscope",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Simon Cozens",
"author_email": "simon@simon-cozens.org",
"download_url": "https://files.pythonhosted.org/packages/fd/27/d0dfaf2ae59d208af7f0cc3213cff5c26864c96a15228e1b9a44e3cfdf86/collidoscope-0.6.5.tar.gz",
"platform": null,
"description": "# collidoscope - brute force detection of glyph collisions\n\n`collidoscope` reports on situations where paths overlap in a shaped\npiece of text. For example, the sequence \"\u063c\u062c\u0628\" might cause a collision like so:\n\n\n\nThis 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:\n\n* Paths in non-adjacent glyphs are never allowed to collide.\n* 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.\n* 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.)\n\nDepending on the length of the string and the number of glyphs tested, this may take a *very* long time.\n\n## Command Line Usage\n\nTo use it:\n\n python3 -m collidoscope -r 0620-064A yourfont.otf\n\nThis creates a collision report on `report.html` for all sequences of three characters within the range 0x620 to 0x64A.\n\n python3 -m collidoscope -r 0620-064A,0679-06D3 -area 10 yourfont.otf\n\nThis 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.\n\n python3 -m collidoscope -c 5 --cursive yourfont.otf\n\nThis 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.\n\n python3 -m collidoscope -c 2 -r 0620-064A --area 5 yourfont.otf\n\nThis just runs an area test for two-character sequences across the basic Arabic range.\n\n## Library Usage\n\n```python\nclass Collidoscope()\n```\n\nDetect collisions between font glyphs\n\n<a name=\"collidoscope.Collidoscope.__init__\"></a>\n#### \\_\\_init\\_\\_\n\n```python\n | __init__(fontfilename, rules, direction=\"LTR\", ttFont=None)\n```\n\nCreate a collision detector.\n\nThe rules dictionary may contain the following entries:\n\n* faraway (boolean): If true, non-adjacent base glyphs are tested for\noverlap. Mark glyphs are ignored. All collisions are reported.\n* marks (boolean): If true, collisions between all pairs of marks in\nthe string are reported.\n* bases (boolean): If *false*, collisions between all pairs of bases in\nthe string are *ignored*.\n* cursive (boolean): If true, adjacent glyphs are tested for overlap.\nPaths containing cursive anchors are allowed to overlap, but\ncollisions between other paths are reported.\n* area (float): If provided, adjacent glyphs are tested for overlap.\nCollisions are reported if the intersection area is greater than\nthe given proportion of the smallest path. (i.e. where cursive\nconnection anchors are not used in an Arabic font, you may wish\nto ignore collisions if the overlaid area is less than 5% of the\nsmallest path, because this is likely to be the connection point\nbetween the glyphs. But collisions affecting more than 5% of the\nglyph will be reported.)\n\n**Arguments**:\n\n- `fontfilename` - file name of font.\n- `rules` - dictionary of collision rules.\n- `ttFont` - fontTools object (loaded from file if not given).\n- `direction` - \"LTR\" or \"RTL\"\n\n<a name=\"collidoscope.Collidoscope.get_glyphs\"></a>\n#### get\\_glyphs\n\n```python\n | get_glyphs(text)\n```\n\nReturns an list of dictionaries representing a shaped string.\n\nThis is the first step in collision detection; the dictionaries\nreturned can be fed to ``draw_overlaps`` and ``has_collisions``.\n\n<a name=\"collidoscope.Collidoscope.draw_overlaps\"></a>\n#### draw\\_overlaps\n\n```python\n | draw_overlaps(glyphs, collisions, attribs=\"\")\n```\n\nReturn an SVG string displaying the collisions.\n\n**Arguments**:\n\n- `glyphs` - A list of glyphs dictionaries.\n- `collisions` - A list of Collision objects.\n- `attribs` - String of attributes added to SVG header.\n\n<a name=\"collidoscope.Collidoscope.has_collisions\"></a>\n#### has\\_collisions\n\n```python\n | has_collisions(glyphs_in)\n```\n\nRun the collision detection algorithm according to the rules provided.\n\nNote that this does not find *all* overlaps, but returns as soon\nas some collisions are found.\n\n**Arguments**:\n\n- `glyphs` - A list of glyph dictionaries returned by ``get_glyphs``.\n \n- `Returns` - A list of Collision objects.\n\n\n## Requirements\n\nThis requires some Python modules to be installed. You can install them like so:\n\n pip3 install -r example-requirements.txt\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Brute force detection of glyph collisions",
"version": "0.6.5",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3b4a10496655ad3b4b57b3697ae0b811bcdee7915a3698518b2176dc5f177942",
"md5": "4e2e205c6e35b958ccd10ca72fcf645c",
"sha256": "9ea466e6aeaeed4f82cb65ae061c997a4e0d0d7cb492671339a4f93c431bb88b"
},
"downloads": -1,
"filename": "collidoscope-0.6.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e2e205c6e35b958ccd10ca72fcf645c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12444,
"upload_time": "2023-02-09T11:09:49",
"upload_time_iso_8601": "2023-02-09T11:09:49.071490Z",
"url": "https://files.pythonhosted.org/packages/3b/4a/10496655ad3b4b57b3697ae0b811bcdee7915a3698518b2176dc5f177942/collidoscope-0.6.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fd27d0dfaf2ae59d208af7f0cc3213cff5c26864c96a15228e1b9a44e3cfdf86",
"md5": "1edb9c38373e1d9fe106a65f8af16fa1",
"sha256": "0fb33327c1598c0fcd4970aa08943d6b4d853cf8b7b785b4abae704480dc7d20"
},
"downloads": -1,
"filename": "collidoscope-0.6.5.tar.gz",
"has_sig": false,
"md5_digest": "1edb9c38373e1d9fe106a65f8af16fa1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 696098,
"upload_time": "2023-02-09T11:09:51",
"upload_time_iso_8601": "2023-02-09T11:09:51.259465Z",
"url": "https://files.pythonhosted.org/packages/fd/27/d0dfaf2ae59d208af7f0cc3213cff5c26864c96a15228e1b9a44e3cfdf86/collidoscope-0.6.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-09 11:09:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "simoncozens",
"github_project": "collidoscope",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "collidoscope"
}
JSON
