ionclaw-org/ionclaw/local-image-generation

Local Image Operations

Use the image_ops tool to create, resize, draw on, and composite images without AI. All operations are programmatic: you specify dimensions, colors, positions, and paths. The tool does not interpret prompts or generate content from text descriptions.

Supported Formats

Input (read): PNG, JPEG, BMP, GIF, TGA, PSD, HDR, PIC, PNM

Output (write): PNG only. All results are saved as PNG regardless of the output file extension.

Tool: image_ops

Supported operations: create, resize, draw_rect, overlay. Choose one per call via the operation parameter.

Parameters

Paths

All paths (output_path, input_path, overlay_path) must resolve to files under the workspace or under public (e.g. public/media/). The tool validates paths and rejects anything outside these directories. Use relative paths such as public/media/canvas.png or paths relative to the workspace root.

Operation: create

Create a new image from scratch. No input image is used.

Required: operation, output_path, width, height Optional: background (default gradient), color (for solid background; default ffffff)

Behavior:

• gradient — Fills the image with a procedural gradient (horizontal and vertical color variation). Useful for placeholders and backgrounds.
• solid — Fills the image with a single color. Set color to hex RRGGBB (e.g. ff0000 for red).

Create a gradient placeholder (e.g. for a hero section):

image_ops(operation="create", output_path="public/media/hero.png", width=1920, height=1080)

Create a solid-color image:

image_ops(operation="create", output_path="public/media/red.png", width=400, height=300, background="solid", color="ff0000")

Create a white canvas:

image_ops(operation="create", output_path="public/media/canvas.png", width=800, height=600, background="solid", color="ffffff")

Create a black banner background:

image_ops(operation="create", output_path="public/media/banner_bg.png", width=1200, height=400, background="solid", color="000000")

Operation: resize

Resize an existing image to new dimensions. Aspect ratio can change.

Required: operation, input_path, output_path, width, height

Behavior: Loads the image at input_path, resizes it to the given width and height, and writes the result to output_path. Supports common formats (PNG, JPEG, etc.) for input; output is PNG.

Resize to thumbnail:

image_ops(operation="resize", input_path="public/media/photo.png", output_path="public/media/photo_thumb.png", width=200, height=200)

Resize to specific dimensions (e.g. social card):

image_ops(operation="resize", input_path="public/media/image.jpg", output_path="public/media/card.png", width=1200, height=630)

Downscale keeping aspect ratio (example 50%):

Compute target dimensions as needed, then call with the desired width and height.

Operation: draw_rect

Draw a filled rectangle on an existing image. Use for panels, bars, masks, or blocking out regions (e.g. where text or a logo will go).

Required: operation, input_path, output_path, x, y, width, height, color

Behavior: Loads the image at input_path, fills the rectangle with top-left at (x, y) and size (width, height) with the given hex color, and writes to output_path. You can set output_path equal to input_path to overwrite the original. Coordinates and dimensions are clamped to the image bounds.

Black bar at top of image:

image_ops(operation="draw_rect", input_path="public/media/banner.png", output_path="public/media/banner.png", x=0, y=0, width=800, height=60, color="000000")

White rectangle (e.g. text area) at (100, 100) with size 400×80:

image_ops(operation="draw_rect", input_path="public/media/slide.png", output_path="public/media/slide.png", x=100, y=100, width=400, height=80, color="ffffff")

Red accent block at bottom-right:

image_ops(operation="draw_rect", input_path="public/media/card.png", output_path="public/media/card.png", x=700, y=450, width=100, height=50, color="ff0000")

Operation: overlay

Paste one image on top of another at a given position. Use for watermarks, logos, badges, or any compositing where one image sits on top of another.

Required: operation, input_path, overlay_path, output_path, x, y Optional: overlay_width, overlay_height — when both are set, the overlay is resized to this size (in pixels) before pasting. Use for a proportional watermark or logo size (e.g. 100×20).

Behavior: Loads the base image at input_path and the overlay at overlay_path. If overlay_width and overlay_height are both positive, the overlay is resized to that size first. Pastes the overlay with its top-left corner at (x, y) on the base. Writes the result to output_path. Overlay is opaque (pixels replace base pixels in that region). If the overlay extends beyond the base image, the excess is clipped.

Watermark at bottom-right (e.g. base 800×600, position 690, 550):

image_ops(operation="overlay", input_path="public/media/photo.png", overlay_path="public/media/watermark.png", output_path="public/media/photo_watermarked.png", x=690, y=550)

Watermark at a specific size (e.g. 100×20) at bottom-right:

image_ops(operation="overlay", input_path="public/media/photo.png", overlay_path="public/media/watermark.png", output_path="public/media/photo_watermarked.png", x=700, y=580, overlay_width=100, overlay_height=20)

Logo at top-left:

image_ops(operation="overlay", input_path="public/media/banner.png", overlay_path="public/media/logo.png", output_path="public/media/banner_with_logo.png", x=10, y=10)

Logo centered horizontally at top (example: base width 800, logo width 200 → x=300):

image_ops(operation="overlay", input_path="public/media/hero.png", overlay_path="public/media/logo.png", output_path="public/media/hero_logo.png", x=300, y=20)

Color format

All colors use hex RRGGBB: 6 hexadecimal digits, no #. Uppercase or lowercase is fine.

Use color in create (with background="solid") and in draw_rect for the rectangle fill.

Workflows

Placeholder then thumbnail

1. Create a gradient image.
2. Resize it to thumbnail dimensions.

image_ops(operation="create", output_path="public/media/hero.png", width=1920, height=1080)
image_ops(operation="resize", input_path="public/media/hero.png", output_path="public/media/hero_thumb.png", width=400, height=225)

Banner with top bar and logo

1. Create gradient banner.
2. Draw a black bar at the top.
3. Overlay the logo at (10, 10).

image_ops(operation="create", output_path="public/media/banner.png", width=800, height=200)
image_ops(operation="draw_rect", input_path="public/media/banner.png", output_path="public/media/banner.png", x=0, y=0, width=800, height=40, color="000000")
image_ops(operation="overlay", input_path="public/media/banner.png", overlay_path="public/media/logo.png", output_path="public/media/banner_final.png", x=10, y=10)

Watermark a photo

1. Overlay the watermark image at the desired position (e.g. bottom-right). Optionally set overlay_width and overlay_height to paste the watermark at a specific size (e.g. 100×20).

image_ops(operation="overlay", input_path="public/media/photo.jpg", overlay_path="public/media/watermark.png", output_path="public/media/photo_watermarked.png", x=700, y=500)

With fixed size 100×20:

image_ops(operation="overlay", input_path="public/media/photo.jpg", overlay_path="public/media/watermark.png", output_path="public/media/photo_watermarked.png", x=700, y=580, overlay_width=100, overlay_height=20)

What NOT to do

• Do not use image_ops when the user wants an image generated from a text description (e.g. "draw a sunset", "create an illustration of a cat"). Use the generate_image tool (AI) for that.
• Do not use a # in color values; use only 6 hex digits (e.g. ff0000, not #ff0000).
• Do not use paths outside the workspace or public/; the tool will reject them.
• Do not assume aspect ratio is preserved in resize; you set both width and height explicitly.

After operations

Return the resulting path to the user so they can open or link to the image (e.g. public/media/result.png or the path you used in output_path).