geo-icon

Geo Icon: draw icons with geometric construction

What you write isconstruction, not an outline. A JSON spec describes circles, rings, tangent lines, leaf shapes bounded by two arcs (lune), tangent arc chains, convex hulls, and boolean operations. The script computes the final outline from this, and draws the same set of primitives back onto the construction sheet as construction lines. So the construction lines are the source of the shape, not decoration pasted on afterwards. This is exactly the difference between the Rikyu sample before/after (see references/method.md）。

Outputs

python3 <本 skill 目录>/scripts/geoicon.py spec.json -o <输出目录> Generated:

File	Content
`icon.svg`	Final mark: monochrome, single evenodd path, square viewBox. Portions of the outline that follow construction circles are written as real SVG arcs `A`, straight segments are written as `L`
`poster.png/.svg`	Finished image centered on an off-white 4:5 canvas
`construction.png/.svg`	Construction sheet: grid paper, shape filled in light gray, construction circles, tangent lines, circle-center crosses, CONCEPT text at the bottom, finished thumbnail at the bottom right. By default only the circles and lines that end up on the final outline are drawn; gap seams are drawn as paired concentric circles
`sizes.png/.svg`	128→16px positive/negative small-size test
`compare.png/.svg`	Only when regularizing an existing icon (`--compare 原图`): original, regularized, and overlay triptych comparison
`report.txt`	Health check: bbox and centroid, fragment count, radius types, overly thin parts, narrow gaps that will blur

Depends on shapely>=2、numpy、Pillow(if missing, run python3 -m pip install -r <本 skill 目录>/requirements.txt). For PNG, tries rsvg-convert, cairosvg, headless Chrome/Edge, and macOS qlmanage in order; if none are available, outputs SVG only. One render takes about 5–10 seconds.

First triage: three cases

The core of this skill istrue geometric construction: shapes are computed from circles, arcs, and straight lines, and the lines on the construction sheet are the source of the shape. Rikyū's geometric logos are made the same way (reverse-engineering its cat and gorilla, all curves are exact arcs, see references/method.md §8）。

Case	Criterion	Which path
Making a new icon, simple subject	Abstract shapes, 1–3 letters, objects, and 10 animals that can be summarized by internal parts	Construction mode (workflow below)
Regularizing an existing icon	User provided an icon image and wants it tidier and more standard	Regularization workflow (see next section)
Subject too complex	Subjects with lots of manes, scales, and curling clouds, such as dragons, qilin, and phoenixes	First suggest simplifying into a geometric silhouette; if the user insists on a complex version, go through the external vector interface `scripts/external.py`. This skill does not bundle any third-party service; the interface is reserved (see `references/external-vector.md`), and if it is not configured, tell the user honestly. Externally generated SVGs use `geoicon.py --svg` for the same poster, small-size test, and health check, but have no construction sheet

Regularize an existing icon

Suited to requests like "my app icon/logo looks a bit off, help me tidy it up". The goal is to find the proportion system the original icon was trying to express, and reconstruct it with exact geometry, rather than redesigning it.

Measurement: python3 <本 skill 目录>/scripts/measure.py icon.png It puts the icon on a 100×100 canvas and lists each part and each hollow's bbox, width, height, center, and shape classification (circle, rectangle, capsule, rounded rectangle), and for side-by-side parts it reports the spacing, width, height ratio, and center-alignment deviation. When a light-colored shape is on a dark background, add --invert。
Read the intent: find relationships that are close to integer ratios, the golden ratio, or equal spacing. For example, heights 19.9 / 42.1 / 64.4 are actually 1:2:3; spacing 12.9 is exactly w + w/φ. The deviation is exactly what needs to be corrected.
Write the spec: derive all dimensions from one modulus (such as the bar width w, or one main radius R); for symmetric parts use mirror, centered on the canvas center.
- For App icons, use the iOS corner radius ratio of 22.37%.
- For an icon with a background-colored square: write the square as backdrop, and the main subject is the ink; the composition card only covers the construction of the main subject.
- Multi-color: use paint to color the parts.
- For shapes like curved-edge triangles (sails, shields, leaves), use arcgon: each edge is an arc, and the radii form a family (such as R, 1.5R, R/φ). For the gap between adjacent parts, pin the two edges on concentric circles (R and R − g), so the gap width is equal everywhere (see examples/sails.json）。
- Regularization changes some of the "hand-drawn looseness." For example, if the gap between the two sails in the original is wide at the top and narrow at the bottom, after regularizing it to equal width, the tip of the rear sail will shift. Such visible changes must be clearly stated at delivery, along with an alternative that preserves the original appearance (for example, using only the same curvature, not concentric circles).
Render and compare:
```
python3 <本 skill 目录>/scripts/geoicon.py spec.json -o out/ --compare icon.png --icon-pad 0 --icon-png 1024
```
compare.png display "original | regularized | overlay" side by side; in the overlay, draw the new outline in red over the semi-transparent original. When there is backdrop , the original is aligned by treating "the whole image = the square," so first crop the screenshot to the edge of the square. --icon-pad 0 --icon-png 1024 Output a full-bleed 1024px icon.
Re-measure: run poster.png again on the newly generated measure.py, and confirm that the deviations in width, spacing, and center are all zero.
Deliver four things; none may be missing:
- construction.png：Composition card, the core evidence of regularization. It shows which circles and lines make up the new icon (corner circles, end circles, axes of symmetry, proportion reference lines); this is exactly the "regularize through geometric construction" that the user asked for. In the spec's guides , add reference lines explaining the proportions (such as the top and bottom edges of the three height levels 1:2:3).
- compare.png: a three-panel comparison of original, regularized, and overlay.
- icon.png / icon.svg: the finished product.
- A before-and-after numeric comparison table: which dimensions changed from what to what, and what the proportion system is.
Also note: submitting an iOS App to the App Store requires a full-bleed square image without rounded corners ("r": 0); the system adds the mask itself; textures such as gradients, strokes, and gloss in the original are outside the scope of this skill; after regularization the result is a purely flat graphic.

Workflow (construction mode)

Define the concept. Write a one-sentence concept (it will be printed on the card), and choose an archetype: an object graphic, an animal silhouette, or a circular badge/family crest. Put the user's brand name in title. If there is none, use the object name.
Break down the parts and find a geometric archetype for each part. First make a list in your head (or in comments), for example "head = circle, body = hull of two circles, tail = chain of tapering tangent arcs." See the table below for a quick reference; for more recipes see references/method.md §5。
A proportional system. In vars put only 2–4 base quantities: one main radius, one gap, and a modulus if necessary. All other dimensions are derived from them (R/phi、2*U). Keep radii to about 5 distinct values, and use a single gap value across the whole drawing. Key points either land on a 0.5 grid or are derived geometrically (polar、on、meet, tangent points).
Write the spec. The canvas is 100×100 with the y-axis pointing down; angle 0°=right, 90°=down, −90°=up; a positive turn is clockwise on screen. For the full syntax see references/spec.md, read it before writing.examples/ The examples in it all run directly, so you can adapt them.
Render.
Check the drawing yourself and iterate 2–4 rounds. Use Read to open construction.png and sizes.png, read report.txt, revise the spec against the checklist below, and render again. The first version almost always needs adjustment: part positions, proportions, whether the gap cuts off small fragments, and whether construction lines are too cluttered.
Deliver. Give the paths of poster.png、construction.png and icon.svg , then explain the construction logic in two or three sentences: which circles you used, what proportions, and where the gap is used to separate layers.

Prototype quick reference

Want to express	Use	Notes
Head, body, wheels, eyes	`circle`	Most commonly used; the same radius reused multiple times
Lens, bullseye, eye socket, outer ring	`ring`	Concentric rings; ring width uses the modulus
Rounded body, buttons	`rect` + `r`	Rounded corners are automatically drawn as construction circles
Leaves, petals, flames, pointed noses of a body, almond-shaped eyes	`lune`，`bulge: [b, -b]`	A vesica formed by two equal arcs
Fins, wings, crescents, mane pieces	`lune`，`bulge: [b1, b2]` Same sign	Two arcs on the same side, forming a crescent
Limbs, neck, beams	The two circles' `hull`, or fixed-width `stroke`	The straight edges of the hull are external common tangents and will be extended into construction lines
Tail, tentacles, vines, ribbons	`turtle` + tapering `w: [粗, 细]`	Formed by a chain of tangent arcs, maintaining G1 continuity
Curls, swirls	`turtle` Steps of `spiral` step	Every 90° the radius × 1/φ, i.e., a golden spiral
Repeated units in flowers, gears, suns, family crests	`repeat`	Rotational array around the center
Left-right symmetry	`mirror`	Automatically draws a dashed axis of symmetry
Foreground parts pressing onto the background	In ink, `{"add": X, "gap": g}`	First carve out a slot around X expanded by g, then fill X. Animal silhouettes use this to separate arms, legs, and tail
Ground line, flat bottom	`{"cut": 地面以下的大 rect}`	Contact points land on the same horizontal line
Make a straight edge bulge slightly outward (back line, forearm)	Overlay a single-valued `lune`	on that tangent; the chord is the original straight edge, and the sagitta is 1.5–3
Smooth concave corners	Modifier `"blend": r`	Only fills concave corners into an arc of radius r, leaving convex arcs unchanged; r is 1–5
A whole organic outline	`chain`	Like a belt wrapped around a series of circles: positive radius is convex, negative radius is concave, 0 is a sharp corner

Complex animal silhouette

Animals are easiest to render as a "bear" or a "robot." These are the patterns we hit while iterating on the gorilla — read them before doing a quadruped or primate. references/method.md §7。

Use a hull of two joint circles for limbs, which gives a clean taper, in the order "muscle → narrowing → hand/foot". Directly intersecting a string of circles turns into beads (balloon animal), and blend won't save it.
Large contours need curvature: for long straight edges like the back line and the front edge of the forearm, overlay a shallow lune to bulge each one out. Small circles plus long tangent lines only give you a rounded polygon that looks like a robot.
Species are identified by features, not by the number of details: a gorilla is the cranial crest, brow ridge, muzzle, forearm hair tufts, and shoulders higher than the rump; a bear has no cranial crest and no thick forearms. First list 3–4 features, then find a geometric construction for each one.
Far-side limbs: place them in the gaps left between the foreground limbs, and don't overlap them with hair tufts or hands/feet, or the gap will cut them into slivers.
Change only one or two things at a time, and check the poster and sizes every round. Keep every version of the spec so you can roll back if it regresses.

Minimal example

{
  "name": "camera", "title": "Camera",
  "concept": "A camera drawn from concentric circles and level, straight edges.",
  "vars": {"U": 3.5, "R0": 20},
  "points": {"C": [50, 55]},
  "shapes": {
    "body":  {"rect": {"c": "C", "w": 72, "h": 46, "r": 13}},
    "hole":  {"circle": ["C", "R0"]},
    "ring":  {"ring": {"c": "C", "r_out": "R0 - U", "r_in": "R0 - 2.3*U"}},
    "glass": {"circle": ["C", "R0 - 3.3*U"]}
  },
  "ink": ["body", {"cut": "hole"}, "ring", "glass"],   // 按顺序：加、挖、再加
  "guides": [{"axis": true}, {"hline": "C.y"}]          // 额外的纯构造线
}

Self-check list

Look at sizes.png：

Is it still recognizable at 32px? At 16px is at least a silhouette left? If not, delete details, thicken, and widen the gaps.

Look at construction.png：

Can you point to which circle or line every contour segment comes from? If not, you're "drawing" rather than "constructing."
Are the construction lines so messy they lose persuasiveness? For purely auxiliary parts, use "guide": false or "circles" to reduce noise. Keep the circles that make the proportions clear.
Is the center of gravity stable? Standing objects need a ground line, and object-type icons are usually strictly symmetric.

Look at report.txt：

tiny island: gap or cut has sliced out isolated small fragments; adjust part positions or the gap.
thin parts: parts thinner than min_feature(2% of the default canvas) will break at small sizes.
tight gaps: gaps narrower than min_gap(1.2% of the default) will blur at small sizes.
radii more than 6: merge similar radii and switch to deriving by ratio.

Overall:

Monochrome, no gradients, no strokes, no text. Negative space is part of the design.
Original. Don't imitate existing brand logos, and don't use copyrighted character designs.

Common pitfalls

lune bulge sign: a positive value bulges to the right-hand side of going from a to b (as seen on screen). Going top to bottom (↓), a positive value bulges left; going left to right (→), a positive value bulges down. For leaf shapes use [b, -b]and ignore direction.
gap order: a gap only affects ink already painted before it (painter's algorithm). Parts that need to be on top go later.
round eats fine details: when the corner radius is larger than half the part's width, the part gets erased entirely.
mirror keeps the original by default（keep: true), and the mirror axis defaults to x=50. Draw only the left half of a part and mirror it to the right.
too many construction lines: every edge of a poly is extended into a full-width line. Parts like triangular ears can keep their lines; for purely auxiliary parts set "guide": false。
Text: don't put text in icons. If a wordmark is needed, suggest it separately in the delivery notes.
The convex circle of a chain must protrude beyond the tangent lines of adjacent circles: otherwise the belt will wrap all the way around it and bulge into a ball. The script automatically skips such circles and writes an entry in report.txt write a line in warning; when you see it, move the circle outward or enlarge it.
blend is not a cure-all: it only fills concave corners. When circles are too far apart, a blend that is too small leaves beaded notches, and one that is too large smooths away features.
radii warning: organic animals usually use 10–20 radii, which is normal. It is enough to keep the radii of the main volumes (torso, head, thighs, upper arms) in families.
For "verifiable" output, use less blend / soften / round: the transition arcs they produce are not construction circles,icon.svg can only be written as polylines, and they cannot be seen on the construction card either.report.txt The first line gives the exact proportions of arcs, straight lines, and polylines in the outline; the goal for geometric logos is polylines close to 0%. When you need a chamfer, use an explicit small circle (added to union or chain) instead.
Construction card too cluttered or too empty: by default, only circles and lines that end up on the final outline are drawn. To see the full construction (for debugging), write "show": "all"in the spec, or add it on the command line --all-guides。