Circlo

What Circlo Is and How to Use It

I ran into this tool when someone on a forum mentioned it for automating circle-based geometry operations, and I decided to dig into it since my own projects involve a lot of SVG manipulation. Circlo turns out to be a relatively small Python library that lets you define circles with parameters, compute intersections, generate tangent lines, and export the results to SVG or JSON without writing all the trig from scratch. The package is on PyPI, so the standard route is pip install circlo. That's it. You don't need any special compiler toolchain or external dependencies beyond NumPy, which gets pulled in automatically. If you're on Python 3.10 or later, you're fine. On older versions the type hints break in places, so I'd recommend sticking to 3.10+ to avoid unnecessary headaches. Creating a circle in Circlo is straightforward. You pass a center point and a radius:

from circlo import Circle
c = Circle(center=(0, 0), radius=5) That gives you an object with a bunch of methods ready to go. The center is stored as a tuple of floats, and the radius must be positive — passing zero or a negative number raises a ValueError immediately, which is reasonable because a circle with no radius isn't useful for any of the downstream geometry.

Common Operations

Here's where it gets practical. The two operations I use most are intersection detection and tangent generation. To find where two circles intersect, you call c1.intersect(c2). It returns a list of (x, y) tuples representing the intersection points. If the circles are too far apart or one is inside the other without touching, you get an empty list. That's important — it doesn't raise an error, it just returns nothing. Beginners sometimes miss that and then wonder why their code crashes on the next line when it tries to unpack a result that doesn't exist. For tangents, c1.tangent_to(c2) gives you the common tangent lines between two circles. The return format is a list of line objects, each with a slope and intercept if you need them in Cartesian form. I found this useful when generating gear-like profiles where I needed clean tangent arcs between adjacent circles.

A real edge case I hit with Circlo

I was working on a layout where two circles were nearly touching — their radii were 5 and 4.9999, and the distance between centers was exactly 9.9999. The floating point math in the intersection method started producing tiny imaginary components due to precision loss, and Circlo would silently include garbage points in the result. I spent about twenty minutes debugging what I thought was a logic error before realizing it was a numerical stability issue. The workaround was simple: I wrapped the intersection call in a tolerance filter that discards any point where the computed distance to either circle's perimeter exceeds 1e-6. Here's roughly what I added: points = c1.intersect(c2)
tolerant_points = [p for p in points if all(abs(dist(p, other.center) - other.radius) 1e-6 for other in (c1, c2))] That fixed the issue without needing to modify the library itself.

Exporting Results

Once you have your circles and computed points, Circlo can export to SVG directly. Circle.to_svg() generates an SVG string with the circle outline. If you have multiple circles, you can concatenate the SVG fragments or use the Group class to manage them together. The SVG output uses standard <circle> elements with cx, cy, and r attributes, so it renders correctly in any modern browser or vector editor. JSON export is also available via Circle.to_json(), which outputs the center coordinates and radius in a clean structure. I use this when I need to pass circle data between a Python backend and a JavaScript frontend.

When Circlo Isn't the Right Tool

It's worth noting that Circlo is focused on 2D Euclidean geometry only. If you need 3D sphere intersections, spherical geometry, or projections on a curved surface, this library won't help you. There's also no built-in support for CAD-style constraints or parametric editing — it's a calculation library, not a modeling environment. For heavy-duty computational geometry work involving many overlapping shapes, you might find that libraries like Shapely or CGAL handle edge cases more robustly, though they have a steeper learning curve and heavier dependency footprint. Despite those limitations, Circlo fills a useful niche. When you need to rapidly prototype circle-based layouts, generate SVG assets for a web project, or compute intersection points without writing trigonometric formulas by hand, it saves time. My experience is that a task that would take me 30 to 45 minutes of manual calculation and coordinate tracking takes about five minutes with Circlo, once I got past the initial tolerance issue mentioned above. You can find it at pip install circlo and the source is on GitHub under the circlo organization. The documentation is sparse but the API is small enough that the docstrings cover most of what you need.