Go tool spins square PNGs into a coin-flip GIF

What it is

go-animate-coin is one main.go, about 280 lines, that does exactly one thing: read a square PNG image — say a coin or token logo — and write out an animated GIF of that image spinning clockwise toward the viewer, as if flipped in front of you. The README states plainly why it was built: its author wanted to animate the $APARIO meme-coin logo for XPMarket.com and couldn't find existing tooling, so the author wrote this one.

The whole program lives in main.go using only Go's standard library — image, image/png, image/gif, flag, math. There are no third-party dependencies; go.mod declares the module path and nothing else beyond go 1.23.4.

What it does

The tool takes a circular image, such as a coin or token logo, and rotates it in perspective toward you "as if the coin is being spun around clockwise facing you," per the README.

It produces 24 frames at 15-degree increments of rotation (0 through 345 degrees). Each frame applies a horizontal squash based on cos(angle), so the coin narrows as it turns edge-on, plus two touches meant to sell the effect:

• Edge darkening — when the coin is near side-on (|sin(angle)| > 0.7), pixels at the outer edges are dimmed by a factor of 0.7, suggesting shading on the rim.
• Neighbor interpolation — adjacent non-transparent source pixels are blended by a factor of |sin(angle)| * 0.5, strongest when the coin is edge-on, smoothing transitions between frames.

The GIF is encoded with gif.DisposalPrevious so each frame clears before rendering the next. The README notes that Claude AI helped debug the transformFrame function; the author describes it as a fun few-hours exercise shared under MIT.

Running it

Install and run:

go install github.com/andreimerlescu/go-animate-coin@latest

./go-animate-coin -input sample/apario-xrp-coin@144px.png \
  -output animated.gif

The flags are few:

-input string     Path to input PNG image
-output string    Path for output GIF (default "animated.gif")
-v                Show version
-y                Override Y/N prompts with Y response

Two constraints matter. The input must be a PNG — JPG, JPEG and WebP are not supported — and it must be square and at least 144x144 pixels, or the program exits with Input image must be squared at least 144x144 pixels.

If your chosen output path already exists and holds content, the tool prompts before overwriting:

File sample/apario-xrp-coin@144px.gif already exists. Overwrite? [y/N]: n
2024/12/23 10:39:08 operation cancelled by user

Answering anything other than y or yes, or passing nothing, cancels the run. The -y flag skips the prompt and overwrites directly.

How it works

The flow in main() is straightforward:

1. Parse flags; print version if -v.
2. Check whether the output file exists and handle overwrite confirmation.
3. Decode the PNG and verify dimensions are square, at least 144x144.
4. Build a GIF palette from the source's unique colors (capped at 256), forcing transparent as the first entry.
5. Create 24 paletted frames with delays[i] = 17 centiseconds each — about six frames per second for a full rotation.
6. Call transformFrame(sourcePNG, frame, angle) for each of the 15-degree angles.
7. Encode all frames to the output GIF.

The core is transformFrame, which uses reverse mapping: rather than pushing source pixels forward into the destination (which leaves gaps), it walks every destination pixel and works backward to find its source coordinate via srcX := int(relX/scale) + centerX. That reverse projection, plus a floor on |cos(angle)| at 0.01 to avoid division by zero, keeps the animation gap-free.

The second function, handleFileOverwrite, guards the output path: it returns early if the file doesn't exist or is empty, errors if the path points to a directory, and otherwise prompts for confirmation unless overridden.

Who it's for

This is a niche utility with no library surface — you import nothing from it; you run its binary. It suits anyone who needs a quick spinning-coin GIF of a circular logo: token projects, badge designers, or people making placeholder animations. The sample directory ships an input PNG and the resulting animated GIF so you can see both ends before running anything.

The README's contribution section describes the usual fork-and-pull-request workflow, and it also mirrors the project on GitLab for those who prefer it there. A tip address list follows — XRP preferred — but that is courtesy, not a requirement of use.

Bottom line

go-animate-coin solves one narrow problem with no dependencies and no configuration: square transparent PNG in, animated spin GIF out. It is small enough to read end-to-end in an afternoon, which makes it easy to trust or to adapt if you need different frame counts or timing than the fixed 24-frame, ~6 fps output.