tangle

What it is

Two cables are wound round each other behind a desk. Before pulling, there is one question worth answering: are they actually locked, or do they only look bad? Pull on a genuinely locked pair and you tighten it into a worse knot. I wanted a tool that answers that from a single photograph, and answers it in one of two ways only: a yes with a proof behind it, or a refusal with a reason. No maybe, and no percentage.

tangle is that tool. It looks at a picture of two cables, builds the diagram of their crossings, and computes the linking number of the pair. The trick is in what it does with the crossings it cannot read. Every crossing has a sign, and the sign needs to know which cable is on top. When the photograph cannot say, tangle does not guess. It treats that crossing as unknown, and with $k$ unknown crossings and a signed sum $S$ over the readable ones, it computes the full set of linking numbers the photograph is consistent with: the interval $[(S-k)/2,\,(S+k)/2]$, in $O(k)$ steps, without enumerating the $2^k$ possibilities.

From that interval there are three outcomes. If the interval excludes zero, the cables are certified LINKED: no motion separates them while their ends are held. If one cable is on top at every crossing between the two, a different witness certifies them SEPARABLE. Otherwise tangle refuses, and when the refusal comes from an unreadable crossing it names that crossing and the camera bearing to re-shoot it from. A linking number of zero is never read as “unlinked”; the Whitehead link has $\mathrm{lk} = 0$ and does not come apart.

The reason for building it this way is a cost asymmetry, which the README puts better than I can paraphrase: “A refusal costs you a second photograph. A wrong certificate tells somebody to leave a live cable plugged in.”

The project splits cleanly in two. The certified layer takes a diagram and returns an exact verdict; its own docstring says the claim is “given a correct diagram, the verdict is exact”, and that nothing in it is evidence that the diagram is correct. The imaging layer turns pixels into that diagram, and it is where the risk lives. I say this first because the measured results split the same way. On diagrams and on scenes tangle renders itself, it certifies often, and none of the certificates in the runs reported here was wrong. On real photographs it has certified nothing: 247 tries, 247 refusals, and not one diagram built.

The figure below shows the first fact the design rests on. Swap which cable is on top at a crossing and the union outline of the two cables does not change by a single pixel. For opaque cables the silhouette carries no depth at all. The only place over/under shows up is in the colour of each cable: whether it runs continuously through the crossing or is interrupted there.

What it can do

The headline claim is narrow on purpose. It is not “tangle is accurate”. It is that the $O(k)$ interval certifies strictly more pairs than refusing on any unknown crossing does, at the same zero error rate. The baseline is four lines of code: if any crossing between the two cables is unreadable, refuse; otherwise take the half-sum. That baseline also scores zero errors, so the gap between the two is the only number in this benchmark that could have come out badly.

The corpus is 400 closed braids on two strands, six letters each, with $k = 0, 1, 2, 3, 4$ of the crossings between the two components set to UNKNOWN: 2,000 closed-braid diagrams. Ground truth is not the package’s own arithmetic. For a closed two-strand braid, $\mathrm{lk}$ is half the signed exponent sum of the word, known in closed form before any code runs, and the bench asserts the diagram layer agrees with it on every entry.

Zero wrong is the expected result here, and I want to be plain about why. The corpus corrupts the input in exactly the one way the interval theorem is proved against, so a correct implementation cannot produce a wrong certificate on it. The 0 wrong row measures the code, not the design, and it ships as a regression test. The control that shows the corpus is not trivially easy is to keep the same diagrams and replace the decision rule with a coin flip on every unknown crossing.

Of the 2,000 entries tangle certified 23.6%, returned NOT CERTIFIED on 6.2% and refused 70.2%. The refusal rate is a function of the blur schedule, up to four of six crossings erased on purpose, and is not a photograph’s refuse rate. Among certified verdicts the number of unknown crossings was $k = 0$ for 276, $k = 1$ for 147 and $k = 2$ for 49; nothing above $k = 2$, because certification needs $|S| > k$ and six letters run out.

The second benchmark goes from picture to verdict. 20 seeded piles of two cables, each rendered under four nuisance arms (clean, blur 1.0 px, blur 3.0 px, antialiased), give 80 scenes. Truth comes from the scene’s own height functions, so over/under is never authored: this scores the reader against the scene rather than against itself.

On the crossings the tracer accepted, over/under was read the right way round 182 times out of 182 (46, 47, 44 and 45 per arm). That says nothing about the crossings it refused.

Then the real images. I collected 247 free-licensed pictures the repository did not make: 99 rope and knot photographs and 72 cabling photographs from Wikimedia Commons, 27 published link diagrams, and 49 single-curve drawings from a Hugging Face set, 51 MB in all, each pinned by sha256.

Not one real image reached the certifier. Every one was stopped by a precondition of the tracer before a diagram existed, and the most common stop, at 104 of 247, was BRANCHED_SKELETON: a cable’s centreline forks because it crosses itself or because two strands merge into one blob. The repository attributes the zero to the corpus rather than the plumbing, because 13 of 20 rendered piles certify through the identical code path, same resize, same alpha handling, same entry point. I think that reading is right, and I also think it should be said without softening: today tangle answers on pictures it renders itself, and on real photographs it says it cannot see, every time. The 19 link diagrams that carry a published linking number score right 0, WRONG 0, no verdict 19. The WRONG column is empty because the tool never answered.

What the certified layer does on a diagram, end to end through the CLI, looks like this. The clasp scene certifies; the pile refuses and says where to stand:

python -m tangle clasp.png          # synth.clasp(sign=+1), seed 1
  CERTIFIED  LINKED                                                 lk = 1
  interval [1, 1]   S = 2      k = 0
  advice   lk = 1 over all 2^0 resolutions.  Unplug one.            exit 0

python -m tangle pile5.png          # synth.pile(5), seed 5
  REFUSED  LK_STRADDLES_ZERO
  look at  crossing 1 at 275,279, camera bearing 152 deg
  advice   the achievable interval [0, 1] contains 0                exit 2

The truth for that pile is $\mathrm{lk} = 0$, and the tool does not say “unlinked”; it says the achievable interval is $[0, 1]$. Exit codes are the verdict, so a shell can branch on them: 0 certified, 1 not certified, 2 refused, 3 bad input. The next figure puts the same certified layer in your hands: draw two cables, set over/under at each crossing or leave it unknown, and read the verdict tangle would print.

How it was made

The object

The object is not a closed link. A photograph shows two pieces of cable that leave the frame, and closing them up at the frame boundary was an earlier design; it was wrong, because the exit points move with the camera, and I deleted the closure. What remains is a two-string tangle with pinned ends.

That convention is a string constant in certify.py and travels on every verdict.

One crossing, two factors

The modelling decision the whole certificate rests on is that a crossing’s sign factors into two parts. One part is planar: the sign of the determinant of the two cables’ in-plane tangent directions at the crossing. It needs no depth at all. The other part is the over/under bit, the only thing a photograph might fail to read.

In the code, base is the sign of the 2D cross product of the two tangents, set to unknown below SIN_MIN = 0.15, and the sign is the product, unknown if either factor is:

# tangle/diagram.py:136-140 @ 563732b
    def sign(self, c: Crossing) -> int | None:
        """base * (+1 if a is over else -1); None if either factor is unknown."""
        if c.base is None or c.over is None:
            return None
        return c.base if c.over == "a" else -c.base

Image coordinates are y-down throughout, which negates every crossing sign relative to the usual mathematical convention. Only $|\mathrm{lk}|$ is certified and the sign is a stated convention, so this costs nothing, but it is written into the module docstring so nobody re-derives it from a failing test.

The half-sum

The linking number is half the sum of the signs over the set $C(A,B)$ of crossings between the two cables. Self-crossings do not enter it.

The half-sum is an isotopy invariant: bend the cables, drape them, re-route them, shoot from the other side, and as long as the four ends stay pinned where they leave the picture, $\mathrm{lk}$ does not move. That is the property a network trained on rope photographs does not have, and it is why I built on an invariant rather than a classifier. None of this layer is new; the half-sum goes back to Gauss in 1833.

From pixels to a diagram

The imaging layer is a chain of stages, and every stage is terminal on refusal. In order: estimate the background from a 12 px border ring in Lab colour; threshold the cable-ness image with Otsu and refuse if the two classes are not separated; clean up the mask; split it into two cables with k-means on colour, refusing if one cluster is empty, too small, or within a just-noticeable difference of the other; estimate the cable width from the distance transform; thin each cable to a skeleton and prune spurs; refuse with BRANCHED_SKELETON if any skeleton pixel still has four or more neighbours; chain the pieces of each cable across occlusion gaps into one curve from frame edge to frame edge, or back to its start, refusing with OPEN_TRACE otherwise; pin the ends to the frame; and build the crossings with the same Diagram.from_polylines the closed-form tests use, so crossing numbering, base and angle are shared code.

The segmentation gate deserves its equation, because it decides most of what a photograph can do. Otsu always returns a threshold, so the refusal comes from Fisher’s ratio of the two classes it found:

The earlier rule required a wide empty run in the histogram of cable-ness. That is satisfiable only by a renderer: a rendered cable is a flat stroke on a flat field, so its histogram is two spikes with nothing between, while a photograph’s is dense in every bin. On the rendered side the new gate also widened the noise envelope from $\sigma = 6/255$ to $\sigma = 16/255$, with 0 unsound certificates across a seven-level, twenty-pile sweep (a figure the repository states in a test docstring).

Reading over and under

Over/under is read from occlusion. Where one cable passes under the other, its own mask is interrupted, and the tracer has to bridge that gap to chain the cable into one curve. The bridged strand is the one underneath. A bridge that explains a crossing at angle $\theta$ should be about $w/\sin\theta$ long, for cable width $w$, so the confidence of a reading is the product of a margin term (one strand bridged, the other not) and a fit term (the bridge has the length its own crossing angle predicts):

Here $g_a, g_b$ are the summed bridge lengths near the crossing on each cable, $K = 1.165$ and $S = 0.85$. The repository reports that $K$ was measured over 72 bridges on 36 seeded piles, with a spread of 0.132 in log units; $S$ is set wide on purpose, to catch a bridge twice or half its predicted length. The code is a direct transcription:

# tangle/vision.py:610-620 @ 563732b
    for c in d.crossings:
        ga = _gap_near(bridges[c.a.cable], c.xy, GAP_R_W * w_est)
        gb = _gap_near(bridges[c.b.cable], c.xy, GAP_R_W * w_est)
        if max(ga, gb) < NOISE_W * w_est:
            out.append(replace(c, over=None, over_conf=0.0, kind="unknown"))
            continue
        over = "b" if ga > gb else "a"
        margin = abs(ga - gb) / (ga + gb)
        pred = BRIDGE_K * w_est / math.sin(math.radians(c.angle_deg))
        fit = math.exp(-((math.log(max(ga, gb) / pred) / BRIDGE_S) ** 2))
        out.append(replace(c, over=over, over_conf=float(margin * fit), kind="read"))

A crossing where neither strand broke has no evidence and is UNKNOWN with confidence 0, never a low-confidence reading. The gate TAU = 0.80 lives inside the certified layer, not in the caller: certify() downgrades any reading below it to UNKNOWN itself, so the honesty boundary sits where a test can hold it. It is a per-rig calibration knob, not a constant.

The certified layer, in order

certify() runs a fixed sequence, and every refusal is terminal. It checks for defects (a free cable end inside the frame, two crossings at one point); then whether the four exit points interleave on the frame, which makes $\mathrm{lk}$ a half-integer; then a parity guard; then the interval; then, only if the interval did not certify, the over-everywhere witness; then a refusal that names a crossing if any crossing is unknown; and otherwise NOT CERTIFIED, either because both cables are on top somewhere (it names the minority crossings, which are the obstructions) or because $\mathrm{lk} = 0$, which is not evidence of anything.

The parity guard is free. For two arcs whose ends do not interleave, $S + k$ must be even. A tracer that misses or invents a single crossing between the two cables makes it odd, and the verdict is ODD_CROSSING_PARITY. For the case the theorem covers, two arcs with ends on the frame or two closed components, that catches every odd-sized tracer error. A pair of one arc and one closed curve is outside it, and there the guard can refuse a correct diagram; that failure is a refusal, never a certificate. The guard cannot catch an even number, which is the subject of the Limitations section.

The repository reports 226 tests passed and 2 skipped. I did not re-run them for this essay; the count is the repository’s own.

What’s new in it

The usual way to answer “is this rope knotted” from a photograph is a learned classifier: show a network many pictures and have it predict a class or a crossing number. The usual way to make a classifier safe is to let it abstain when its confidence is low. And the usual way to handle a crossing whose over/under cannot be read is either to drop the whole input or to commit to a best guess. tangle replaces all three with one exact statement.

Both factors of $\varepsilon(c)$ are $\pm 1$, so the linking number is affine in every crossing the photograph could not read. Each unknown crossing contributes either $+1$ or $-1$ to the sum, independently. With $S$ the signed sum over the readable crossings between the two cables and $k$ unreadable ones, the set of linking numbers achievable over all $2^k$ resolutions is exactly $k+1$ consecutive integers:

The code is short enough to quote whole:

# tangle/certify.py:122-139 @ 563732b
def lk_interval(d: Diagram, i: int = 0, j: int = 1) -> Interval:
    """T4, in O(k), with no enumeration.

    S is the signed sum over the readable inter-component crossings; k counts the ones
    whose sign is unknown for any reason -- unreadable over/under, or a tangent too nearly
    parallel for base.  Both are the same unknown +/-1 in the same product.
    """
    S = 0
    k = 0
    for c in d.between(i, j):
        s = d.sign(c)
        if s is None:
            k += 1
        else:
            S += s
    if (S + k) % 2 != 0:
        raise ValueError(f"S + k is odd (S={S}, k={k}); parity_ok must be checked first (T2)")
    return Interval(lo=(S - k) // 2, hi=(S + k) // 2, known_sum=S, unknown=k)

Three things follow, and they are what I consider new in this project as opposed to in its mathematics.

First, the decision rule has no fourth case. Certification is $\mathrm{lk}_{\min} > 0$ or $\mathrm{lk}_{\max} < 0$, and because the interval is contiguous with step 1, those two plus “straddles zero” are exhaustive. This is an interval certificate, not a confidence score. Flipping the over/under at any crossing of a plane diagram yields another diagram a real pair of cables could form, so the $2^k$ orbit is the exact set of tangles consistent with what the camera saw, not a superset and not a sample.

Second, the certificate points one way. A nonzero linking number proves the cables cannot be separated with their ends held; a zero linking number proves nothing. Separability comes from a different witness that points the other way: if one cable is the over-strand at every crossing between the two, and the ends do not interleave, a disk separates them. That witness needs every one of those crossings read, and it never fires from $\mathrm{lk} = 0$. The word unlinked is a banned substring in the package, enforced by a test that greps the source and every verdict the example set can produce.

Third, a refusal is an answer with an instruction. When the interval straddles zero, tangle computes how many crossings must be resolved before any certificate is possible, $r_{\min} = (k - |S|)/2 + 1$ (necessary, not sufficient), and names the unknown crossing with the most tangential angle, together with a camera bearing along the bisector of its two tangents. I should be exact about how much that naming is worth. The ranking is a perception heuristic about which crossing a new view is most likely to resolve. It is not an information criterion: because $\mathrm{lk}$ is affine, every unknown shrinks the interval by exactly one and no crossing is more decisive than another. I predicted before measuring that it would not beat random, and it did not: 19.9% certified after re-shooting the named crossing, against 20.0% for a uniformly random crossing at the same budget, over 1,404 straddles.

What no one else built

The certified layer is classical mathematics and I make no claim on it. The question for this section is whether the combination around it, an exact interval over the unreadable crossings of a photographed diagram used as a decision rule with refusals, exists elsewhere. These are the closest pieces of prior work I could find, and how each differs.

Matsuno, Tamaki, Arai and Fukuda (2006), Manipulation of deformable linear objects using knot invariants to classify the object condition based on image sensor information, IEEE/ASME Transactions on Mechatronics. By its title this reads as the same pipeline: image, topological rope model, knot invariant, decision, twenty years ago. The paper is paywalled and I have not read it. If its invariant turns out to be the linking number, my claim scopes down to the explicit UNKNOWN state per crossing, the interval over the unknown-crossing orbit, the pinned-end tangle, and the refusal that names a crossing.

Dranowski, Kabkov and Tubbenhauer (2025), On knot detection via picture recognition. Their stated goal is to take a photo of a knot and have a phone recognise it; the present work gives CNN and transformer baselines that predict crossing number directly from images, with a planned route through planar-diagram codes to invariants. Their abstract does not describe a way to carry unreadable crossings through to the invariant, or to abstain. tangle predicts nothing: it computes the set of values the readable crossings allow and answers only when that set decides.

Knots-10, Nie and Yue, Physical Knot Classification Beyond Accuracy. A 1,440-image, ten-class benchmark of physical knots, trained on loose knots and tested on tight ones, reporting that phone-photo accuracy drops by 58 to 69 percentage points. It has what tangle lacks, real rope photographs at scale. tangle has no training at all, and the invariant does not depend on material or colour by construction. I have not run tangle on their images, so I do not claim it does better there; on the 247 real images I did run, it answered nothing.

HANDLOOM, Viswanath et al., Learned Tracing of One-Dimensional Objects for Inspection and Manipulation. A learned tracer that fits a trace to a greyscale image of cables and classifies crossings, trained on simulated and real examples and used for inspection and robot manipulation. It is a better tracer than mine on real images. What tangle adds is downstream of any tracer: an exact integer from the trace, and a refusal when the trace does not decide it.

KnotDLO, Dinkel et al., Toward Interpretable Knot Tying. It acts: it ties an overhand knot with one hand, with no demonstrations or training, succeeding in half of 16 trials from unseen configurations. tangle does not act. It certifies a topological fact about a still picture.

SnapPy and Spherogram (docs) and pyknotid (docs). These compute every invariant tangle computes, and many more, better and more generally. Spherogram builds a link from a planar-diagram code in which every crossing is specified; pyknotid works from space curves, coordinates that already contain depth. Both start from an input in which over/under is known. tangle’s whole contribution sits in the step they assume away: getting that input from a photograph, and saying exactly what follows when part of it is missing. They are also the third-party cross-check tangle does not yet have.

KnotPlot, Scharein (knotplot.com). An interactive program for visualising and building three- and four-dimensional knots, from a database, by sketching, or by construction. Its input is a curve the user makes, not a photograph.

Selective classification. Chow (1970) set out the trade-off between error and rejection, and Geifman and El-Yaniv (2017) build a selective classifier on a trained network by thresholding its softmax response, so that a chosen error rate holds with high probability at test time. tangle shares the instinct, refuse rather than err, but the mechanism is different. Its refusal is not a threshold on a score; it is the outcome when the exact set of consistent answers contains zero. Given a correct diagram there is no error rate to bound. I should not overstate this: the over/under reader upstream does use a thresholded score, TAU, and that is exactly where the guarantee stops.

Put together: in the work I could find and read, I did not find a system that keeps an explicit UNKNOWN per crossing of a photographed diagram, computes the exact set of linking numbers over all resolutions of those unknowns in $O(k)$, certifies only when that set excludes zero, certifies separability through an independent witness, and otherwise refuses and names the crossing to re-shoot. With Matsuno et al. unread, I hold that as a statement about what I found, not a claim to be first. The two figures below run the comparison that matters: the same input through three decision rules, live and then as measured.

Limitations

The first limitation is the one already in the hero. tangle has been run on real images and it certified none of them. 247 free-licensed images produced 0 certified verdicts, 0 wrong certificates, and 0 diagrams built. The dominant refusal is BRANCHED_SKELETON, 104 of 247: on a real pile most crossings are self-crossings, a knot photograph is one rope crossing itself, and a published link diagram is drawn with a black outline that welds strands into one region. The repository attributes the zero to the corpus, not the plumbing, because the same harness certifies 13 of 20 rendered piles through the same PNG round trip. Both halves of that are true at once: the harness works, and the corpus of real pictures is outside what it can trace. Resolving a forked centreline by continuing each cable’s direction through the junction, with a margin so an ambiguous blob still refuses, is the one change that could move the real number off zero. It is not built.

The rest, stated flatly:

• Two visually distinct cables, or it refuses. Colour does segmentation, so a pile of identical black charging cables is one mask and NOT_TWO_COMPONENTS: 61 of 247 real images. The most common real scene is the worst case.
• Noise is a cliff, not a slope. At $\sigma = 16/255$ ten of ten rendered piles trace; at $26/255$ none do, all refused NO_INTENSITY_GAP. The failure direction is always a refusal.
• Every benchmark percentage except the real-image table comes from the repository’s own renderer or from closed-form diagrams. That includes the coverage table, the 182 of 182 over/under readings, the 47 wrong coin-flip certificates, TAU, BRIDGE_K, and the blur and antialiasing arms. The renderer draws matte, constant-colour cables with no shadow, specular highlight, JPEG or lens, and rejects self-crossings, crossings closer than four widths and crossing angles below 25 degrees. A renderer cannot falsify the module that reads it.
• On rendered scenes the interval theorem certified nothing the plain half-sum would not have. All 63 certified verdicts had $k = 0$. The 10.3-point gap exists on the braid corpus, where the unknowns are injected on purpose.
• No camera model. Invariance is tested as diagram-move invariance (Reidemeister moves), which is weaker than camera invariance. The two-view interval intersection exists in certify.intersect, where disjoint intervals would prove one trace wrong, and it is not wired up.
• The rendered corpus cannot exhibit $|\mathrm{lk}| \ge 2$. An arch weaving across an arch cannot wrap twice; $|\mathrm{lk}| \ge 2$ lives only in the torus-link family, which never goes through a camera.
• Only $|\mathrm{lk}|$ is certified. The sign is a stated convention, because image coordinates are y-down.
• The certificate answers a narrower question than you will ask. “Cannot be separated with the ends held” is not “will be annoying to untangle”. A pile with $\mathrm{lk} = 0$ can still be a nightmare of friction.
• The Alexander determinant is not part of the verdict. alexander.py computes $\det(L) = |\Delta_L(-1)|$ from a Goeritz matrix, is exported, and is tested against a closed-form ladder ($\det T(2,n) = n$, figure-eight 5, Whitehead 8). But certify.py and the CLI do not call it; the verdict is the linking number only. The determinant is nonlinear in the unknowns, so no interval of the $O(k)$ kind exists for it, and it would need the $2^k$ enumeration under a budget of $2^{16}$ lifts.
• Two controls named in the specification were not run: the R2-drape alternation control and the mask-overlap control. bench.py prints their absence.

The one limitation I consider most important is quieter than the zero. An even number of tracer errors is not caught, and it can produce a confidently wrong certified integer. Parity catches every odd-sized error for free; nothing in a single view catches a pair. The repository calls this the live false-certification path. The figure below shows it directly: delete crossings from correct diagrams and watch the guard refuse at odd counts and pass at even ones, sometimes with the wrong integer.

The design itself went through several verdicts that are now dead. They are listed with what killed each, because each one changed the code.

Never claimed, in any code path or string: unlinked from $\mathrm{lk} = 0$; unknotted from $\det = 1$; a knot name from any determinant; chirality; a probability or percentage attached to a verdict; any climbing, rigging or safety verdict; anything about the cables outside the frame.

Read more

tangle has no project site of its own; the repository is the place to go. It installs from PyPI as tanglekit; the import and the command stay tangle. Short link: teerth.dev/tangle. Every file reference in this essay is pinned at commit 563732b.

• README.md: the statement, the verdict table, the benchmarks, prior art, what was wrong, and the limits collected once.
• RESULTS.md: every table with the command that produced it, every control, every arm that lost, and the claims not earned.
• tangle/certify.py: the certified layer, theorems T2 to T7, the interval, the two witnesses and the refusals.
• tangle/diagram.py and tangle/vision.py: the sign factorisation, and the imaging layer with its refusals.
• bench.py and real.py: the coverage benchmark and the real-image run.

Related essays on this blog: nerve, which computes linking numbers on polymers; and the other two certify-or-refuse tools, separatrix and planimeter.

@misc{sharma2026tangle,
  author = {Teerth Sharma},
  title = {tangle},
  howpublished = {\url{https://teerth.blog/tangle}},
  year = {2026},
  note = {CC BY 4.0}
}