circle-png-image

Convert PNG images into circular PNG avatars with transparent corners. Use when the user asks to crop, mask, cut out, or convert a PNG image into a circle.

What This Skill Does

Use this skill to turn any PNG image into a circular PNG with transparency outside the circle. It is intended for avatars, profile photos, icons, and other round image assets.

The default behavior is:

1. Open the input PNG.
2. Convert it to RGBA so transparency is preserved.
3. Center-crop the image to a square using the shorter side.
4. Apply a circular alpha mask.
5. Save the result as a PNG.

Quick Start

Run the helper script:

python scripts/circle_png.py input.png output.png

If the system uses python3:

python3 scripts/circle_png.py input.png output.png

Options

Set an exact output size:

python scripts/circle_png.py input.png output.png --size 512

Preserve the entire image by padding it to a square before applying the circular mask:

python scripts/circle_png.py input.png output.png --fit contain

Overwrite an existing output file:

python scripts/circle_png.py input.png output.png --force

Dependency

The script requires Pillow. If it is missing, install it in the active Python environment:

python -m pip install pillow

Prefer a virtual environment when modifying a project:

python -m venv .venv
.venv/Scripts/python -m pip install pillow
.venv/Scripts/python scripts/circle_png.py input.png output.png

On macOS or Linux, use .venv/bin/python instead of .venv/Scripts/python.

Agent Instructions

When the user asks to make a PNG circular:

1. Confirm the input image path and desired output path. If no output is specified, use the input name with -circle.png appended before the extension.
2. Use scripts/circle_png.py to generate the output.
3. Use --fit cover by default for avatar-style results.
4. Use --fit contain when the user says to preserve the full image.
5. Use --size only when the user asks for a specific output dimension.
6. Never overwrite an existing output unless the user explicitly asks or --force is appropriate.

Notes

• Output is always PNG with an alpha channel.
• Non-square inputs are centered automatically.
• The circle touches the output square's edges.