gimp-mcp-plugin 0.1.0__py3-none-any.whl

gimp_mcp_docs/best_practices.md

@@ -0,0 +1,290 @@
+# GIMP MCP Best Practices & Recipes
+
+## ✅ FILLING SHAPES - The Right Way
+
+**DO: Use Polygon Selection for Filled Shapes**
+```python
+# Best method for solid filled shapes
+points = [x1, y1, x2, y2, x3, y3, ...]  # Flat array of coordinates
+Gimp.Image.select_polygon(image, Gimp.ChannelOps.REPLACE, points)
+Gimp.context_set_foreground(color)
+Gimp.Drawable.edit_fill(drawable, Gimp.FillType.FOREGROUND)
+Gimp.Selection.none(image)
+Gimp.displays_flush()
+```
+
+**DON'T: Use Paintbrush for Filling Areas**
+```python
+# ❌ This creates thin strokes, not solid fills
+points = [x1, y1, x2, y2, x3, y3, ...]
+Gimp.paintbrush_default(drawable, points)  # Creates outline only!
+```
+
+**WHY**: The paintbrush tool draws along a path with the current brush size. For solid fills, polygon selection ensures complete coverage.
+
+## ✅ BEZIER PATHS - For Outlines Only
+
+**DO: Use Bezier Paths for Smooth Outlines**
+```python
+# Bezier paths are perfect for stroked outlines with curves
+path = Gimp.Path.new(image, 'curved_outline')
+image.insert_path(path, None, 0)
+stroke_id = path.bezier_stroke_new_moveto(x1, y1)
+path.bezier_stroke_cubicto(stroke_id, cx1, cy1, cx2, cy2, x2, y2)
+# Stroke creates the outline
+Gimp.Drawable.edit_stroke_item(drawable, path)
+Gimp.displays_flush()
+```
+
+**DON'T: Try to Fill Bezier Paths Directly**
+```python
+# ❌ This method doesn't exist in GIMP 3.0
+path.to_selection()  # AttributeError!
+```
+
+**WHY**: GIMP 3.0's bezier paths are designed for vector strokes. For filled curved shapes, approximate with polygon selections or use multiple overlapping ellipses.
+
+## ✅ VARIABLE PERSISTENCE - Reuse, Don't Repeat
+
+**DO: Initialize Once, Reuse**
+```python
+# First call - set up context
+["from gi.repository import Gimp, Gegl",
+ "images = Gimp.get_images()",
+ "image1 = images[0]",
+ "layer1 = image1.get_layers()[0]",
+ "drawable1 = layer1"]
+
+# Later calls - variables still available
+["Gimp.Selection.all(image1)",
+ "Gimp.Drawable.edit_fill(drawable1, Gimp.FillType.FOREGROUND)"]
+```
+
+**DON'T: Repeat Imports and Initialization**
+```python
+# ❌ Wasteful - these persist between calls
+["from gi.repository import Gimp",  # Already imported!
+ "images = Gimp.get_images()",      # Already have this!
+ "image1 = images[0]"]              # Already assigned!
+```
+
+**WHY**: PyGObject console maintains a persistent Python environment. Variables, imports, and functions remain in memory between calls.
+
+---
+
+## ✅ SELECTION FEATHERING - Use Sparingly
+
+**DO: Use Sharp Selections by Default**
+```python
+# Most shapes should have clean, sharp edges
+points = [x1, y1, x2, y2, x3, y3, ...]
+Gimp.Image.select_polygon(image, Gimp.ChannelOps.REPLACE, points)
+# NO feathering - fills will have sharp, clean edges
+Gimp.Drawable.edit_fill(drawable, Gimp.FillType.FOREGROUND)
+Gimp.Selection.none(image)
+```
+
+**DON'T: Add Feathering Without Good Reason**
+```python
+# ❌ This creates blurry, unclear edges
+Gimp.Image.select_ellipse(image, Gimp.ChannelOps.REPLACE, x, y, w, h)
+Gimp.Selection.feather(image, 10)  # Blurs the edges!
+Gimp.Drawable.edit_fill(drawable, Gimp.FillType.FOREGROUND)
+```
+
+**WHEN to Use Feathering:**
+- Soft shadows or glows
+- Blending elements naturally into backgrounds
+- Creating soft, artistic effects
+- ONLY when explicitly requested by user
+
+**WHY**: Sharp edges look professional and clean. Feathering creates blurry, unclear edges that make drawings look unprofessional unless specifically needed for artistic effect.
+
+---
+
+## Common Recipes
+
+### Initialization
+```python
+# Basic initialization
+["from gi.repository import Gimp, Gegl"]
+
+# Recommended full initialization
+["from gi.repository import Gimp, Gegl",
+ "images = Gimp.get_images()",
+ "image1 = images[0]",
+ "layer1 = image1.get_layers()[0]",
+ "drawable1 = layer1"]
+```
+
+### Setting Colors
+```python
+# Set foreground to red
+["red_color = Gegl.Color.new('red')",
+ "Gimp.context_set_foreground(red_color)"]
+
+# Set foreground to black
+["black_color = Gegl.Color.new('black')",
+ "Gimp.context_set_foreground(black_color)"]
+
+# Set background to white
+["white_color = Gegl.Color.new('white')",
+ "Gimp.context_set_background(white_color)"]
+```
+
+### Drawing Operations
+
+**Draw a Line**
+```python
+["Gimp.pencil(drawable1, [0, 0, 200, 200])",
+ "Gimp.displays_flush()"]
+```
+
+**Draw a Filled Ellipse**
+```python
+["Gimp.Image.select_ellipse(image1, Gimp.ChannelOps.REPLACE, 100, 100, 30, 20)",
+ "Gimp.Drawable.edit_fill(drawable1, Gimp.FillType.FOREGROUND)",
+ "Gimp.Selection.none(image1)",
+ "Gimp.displays_flush()"]
+```
+
+**Paint a Curve with Brush (for strokes, not fills)**
+```python
+# Note: Use this for decorative strokes or outlines, NOT for filling shapes
+["Gimp.paintbrush_default(drawable1, [50.0, 50.0, 150.0, 200.0, 250.0, 50.0, 350.0, 200.0])",
+ "Gimp.displays_flush()"]
+```
+
+**Draw a Bezier Curve (for outlines)**
+```python
+["path = Gimp.Path.new(image1, 'my_bezier_path')",
+ "image1.insert_path(path, None, 0)",
+ "stroke_id = path.bezier_stroke_new_moveto(100, 100)",
+ "path.bezier_stroke_cubicto(stroke_id, 150, 50, 250, 150, 300, 100)",
+ "Gimp.Drawable.edit_stroke_item(drawable1, path)",
+ "Gimp.Selection.none(image1)",
+ "Gimp.displays_flush()"]
+```
+
+### Image Management
+
+**Create a New Image**
+```python
+["from gi.repository import Gimp, Gegl",
+ "image1 = Gimp.Image.new(350, 800, Gimp.ImageBaseType.RGB)",
+ "layer1 = Gimp.Layer.new(image1, 'Background', 350, 800, Gimp.ImageType.RGB_IMAGE, 100, Gimp.LayerMode.NORMAL)",
+ "image1.insert_layer(layer1, None, 0)",
+ "drawable1 = layer1",
+ "white_color = Gegl.Color.new('white')",
+ "Gimp.context_set_background(white_color)",
+ "Gimp.Drawable.edit_fill(drawable1, Gimp.FillType.BACKGROUND)",
+ "Gimp.Display.new(image1)"]
+```
+
+**Get Open Filenames**
+```python
+["print([x.get_file().get_path() for x in Gimp.get_images()])"]
+```
+
+**Copy Layer Between Images**
+```python
+["image1 = Gimp.get_images()[0]",
+ "image2 = Gimp.get_images()[1]",
+ "width = image1.get_width()",
+ "height = image1.get_height()",
+ "image1.select_rectangle(Gimp.ChannelOps.REPLACE, 0, 0, width, height)",
+ "image1_layers = image1.get_selected_layers()",
+ "drawable = image1_layers[0]",
+ "Gimp.edit_copy([drawable])",
+ "image2_layers = image2.get_layers()",
+ "target_drawable = image2_layers[0]",
+ "floating_sel = Gimp.edit_paste(target_drawable, True)[0]",
+ "Gimp.floating_sel_anchor(floating_sel)",
+ "Gimp.displays_flush()"]
+```
+
+---
+
+## Tips & Guidelines
+
+### Verification After Drawing
+After drawing operations, capture a high-resolution region to verify output quality:
+- Use `get_image_bitmap()` with region parameter to check specific areas
+- Extract only the modified area (saves resources, faster feedback)
+- Can use higher resolution for small regions
+- Example: After drawing a face, get just the face region at high quality
+- Catch issues early before continuing to next elements
+
+### Context State Awareness
+Check `get_context_state()` before operations that depend on settings:
+- User can change colors, brush, or settings in GIMP UI at any time
+- Verify foreground/background colors before drawing
+- Check if feathering is enabled (to avoid unwanted blurry edges)
+- Ensure opacity and blend mode are as expected
+- Example: Before drawing red circle, verify foreground is actually red
+
+### API Verification
+- Before executing any API command you haven't verified, consult the documentation at https://developer.gimp.org/api/3.0/libgimp/
+- After executing a command, verify GIMP responded with a successful message, e.g., `{"status": "success", "results": ["", "", ...]}`
+
+### Display Updates
+- After drawing operations, always call `Gimp.displays_flush()`
+- After selection operations for drawing, unselect with `Gimp.Selection.none(image)`
+
+### Layer Management
+- When filling layers with color, ensure the layer has an alpha channel using `Gimp.Layer.add_alpha()`
+- Use `Gimp.Drawable.fill()` for reliable full-layer fills
+- Specify colors precisely with `rgb(R, G, B)` or `rgba(R, G, B, A)` to avoid transparency issues
+
+### Context Efficiency
+- No need to repeat import commands - once imported, packages remain available
+- Variables persist between calls - initialize once, reuse many times
+- Use `Gimp.context_push()` and `Gimp.context_pop()` to save/restore context when needed
+
+---
+
+## ✅ SELF-CRITIQUE CHECKLIST
+
+After calling `get_image_bitmap()`, systematically check:
+
+### Visual Inspection
+- [ ] Do all shapes match their intended form?
+- [ ] Are edges sharp and clean (not blurry)?
+- [ ] Are colors correct and consistent?
+- [ ] Are there any unwanted overlaps or artifacts?
+- [ ] Is the overall composition balanced?
+
+### Technical Inspection
+- [ ] Are elements on correct layers?
+- [ ] Were all selections cleared after use?
+- [ ] Is Gimp.displays_flush() called after drawing?
+- [ ] Are feather/antialiasing settings appropriate?
+
+### Common Artifacts to Look For
+- **Blurry/cloudy edges**: Usually from unwanted feathering - remove feathering for clean edges
+- **Cloudy areas**: From feathered selections overlapping - avoid feathering unless explicitly needed
+- **Missing elements**: Drew on wrong layer or forgot flush
+- **Unexpected colors**: Forgot to set foreground/background color
+- **Rectangular artifacts**: Forgot to clear selection
+
+### Action Based on Inspection
+
+**If everything looks good:**
+- Proceed to next phase
+- Document what works for future reference
+
+**If issues found:**
+- STOP drawing new elements
+- Identify which layer has the problem
+- Fix on that specific layer
+- Validate fix with another get_image_bitmap()
+- Only continue when satisfied
+
+**Never:**
+- Paint over problems (creates more problems)
+- Continue when something looks wrong
+- Skip validation "to save time"
+
+---
+
+These patterns are based on practical experience and will help you succeed faster with GIMP MCP operations.

gimp_mcp_docs/iterative_workflow.md

@@ -0,0 +1,311 @@
+# Iterative Workflow with GIMP MCP
+
+## The Golden Rule
+
+**Check your work after every 3-5 operations. Don't continue blindly.**
+
+## Why Iterative Workflow Matters
+
+### Common Problems Without Validation
+- AI treats GIMP like a single-canvas drawing tool
+- Paints everything on one layer, creating overlapping messes
+- Doesn't check work until explicitly asked
+- Fixes problems by painting over them, creating more problems
+- Doesn't leverage GIMP's powerful features (layers, masks, selections)
+
+### The Better Approach
+- Use layers to separate elements (background, body, head, details)
+- Check work after each major step
+- Use proper selection tools and masks
+- Build incrementally with validation
+- Fix issues properly by working on the right layer
+
+---
+
+## Phase-Based Workflow
+
+### Phase 1: Planning (BEFORE drawing anything)
+```python
+# 1. Understand what you're working with
+metadata = get_image_metadata()
+print(f"Canvas: {metadata['basic']['width']}x{metadata['basic']['height']}")
+print(f"Existing layers: {len(metadata['structure']['layers'])}")
+
+# 2. Plan your layer structure
+# Example for drawing an animal:
+# - background_layer: sky and ground
+# - body_layer: main body and legs
+# - head_layer: head and ears
+# - details_layer: eyes, nose, facial features
+# - texture_layer: fur/wool texture overlay
+```
+
+### Phase 2: Layer Setup
+```python
+# Create layers BEFORE drawing
+["from gi.repository import Gimp",
+ "images = Gimp.get_images()",
+ "image = images[0]",
+ "width = image.get_width()",
+ "height = image.get_height()",
+
+ # Create layers from back to front
+ "body_layer = Gimp.Layer.new(image, 'Body', width, height, Gimp.ImageType.RGBA_IMAGE, 100, Gimp.LayerMode.NORMAL)",
+ "image.insert_layer(body_layer, None, 0)",
+
+ "head_layer = Gimp.Layer.new(image, 'Head', width, height, Gimp.ImageType.RGBA_IMAGE, 100, Gimp.LayerMode.NORMAL)",
+ "image.insert_layer(head_layer, None, 0)",
+
+ "details_layer = Gimp.Layer.new(image, 'Details', width, height, Gimp.ImageType.RGBA_IMAGE, 100, Gimp.LayerMode.NORMAL)",
+ "image.insert_layer(details_layer, None, 0)"]
+```
+
+### Phase 3: Incremental Drawing with Validation
+
+**Pattern:**
+1. Set active layer
+2. Draw 3-5 elements
+3. Validate with get_image_bitmap()
+4. Review and fix issues
+5. Repeat
+
+**Example:**
+```python
+# Step 1: Draw body on body layer
+call_api("exec", ["pyGObject-console", [
+    "drawable = body_layer",
+    # Draw body operations...
+    "Gimp.displays_flush()"
+]])
+
+# Step 2: VALIDATE (critical!)
+bitmap = get_image_bitmap(max_width=1024, max_height=1024)
+# STOP and analyze the bitmap image you just received:
+# 1. Describe what you see in the image
+# 2. Compare to what you intended to draw
+# 3. Identify specific problems (blurry edges? wrong colors? missing elements?)
+# 4. Decide: continue or fix?
+
+# Step 3: Fix issues if any (on correct layer!)
+if issues_found:
+    call_api("exec", ["pyGObject-console", [
+        "drawable = body_layer",  # Work on right layer
+        # Fix operations...
+        "Gimp.displays_flush()"
+    ]])
+
+# Step 4: Move to next layer
+call_api("exec", ["pyGObject-console", [
+    "drawable = head_layer",
+    # Draw head operations...
+    "Gimp.displays_flush()"
+]])
+
+# Step 5: VALIDATE again
+bitmap = get_image_bitmap(max_width=1024, max_height=1024)
+# STOP and analyze: Does the head look correct? Any issues to fix?
+```
+
+---
+
+## Common Mistakes to Avoid
+
+### ❌ Mistake 1: Painting Over Problems
+```python
+# WRONG: Nose got covered, so paint over everything
+["Gimp.context_set_foreground(face_color)",
+ "# Paint large area to cover the problem",
+ "# This creates more mess!"]
+```
+
+### ✅ Correct: Fix on Right Layer
+```python
+# RIGHT: Fix the specific issue
+["# Switch to layer that has the problem",
+ "drawable = head_layer",
+ "# Clear the area properly with selection or edit_clear",
+ "# Redraw just what's needed",
+ "Gimp.displays_flush()"]
+
+# Then validate
+get_image_bitmap(max_width=1024, max_height=1024)
+```
+
+### ❌ Mistake 2: No Validation Until End
+```python
+# WRONG: Draw 50 operations then check
+draw_background()
+draw_body()
+draw_head()
+draw_details()
+draw_texture()
+# Now check... oh no, something went wrong at step 2!
+```
+
+### ✅ Correct: Continuous Validation
+```python
+# RIGHT: Validate frequently
+draw_background()
+validate()  # ← Check here
+
+draw_body()
+validate()  # ← And here
+
+draw_head()
+validate()  # ← And here
+# Much easier to fix problems early!
+```
+
+---
+
+## Self-Critique Questions
+
+After each validation with `get_image_bitmap()`, ask yourself:
+
+### 1. Layer Issues
+- Are elements on the correct layer?
+- Are layers overlapping correctly?
+- Do I need to reorder layers?
+
+### 2. Visual Quality
+- Do shapes look like I intended?
+- Are edges sharp and clean (not blurry)?
+- Are colors correct? (Use get_context_state() to verify)
+- Are there unwanted artifacts or overlaps?
+- Did I avoid unnecessary feathering? (Check get_context_state())
+
+### 2a. Regional Verification (Efficient)
+- Instead of checking full image, extract just the modified region
+- Higher resolution possible for small areas
+- Faster feedback, saves resources
+- Example: get_image_bitmap(region={"origin_x": 100, "origin_y": 50, "width": 200, "height": 200})
+
+### 3. Selection Cleanup
+- Did I clear selections after drawing?
+- Are there selection artifacts visible?
+
+### 4. Next Steps
+- Is it safe to continue, or should I fix this first?
+- What's the next logical element to draw?
+- Which layer should it go on?
+
+---
+
+## Advanced: Layer Management
+
+### Create Multiple Layers
+```python
+# Create organized layer structure
+["from gi.repository import Gimp",
+ "image = Gimp.get_images()[0]",
+ "width, height = image.get_width(), image.get_height()",
+
+ # Background layer
+ "bg_layer = Gimp.Layer.new(image, 'Background', width, height, Gimp.ImageType.RGBA_IMAGE, 100, Gimp.LayerMode.NORMAL)",
+ "image.insert_layer(bg_layer, None, 0)",
+
+ # Object layer
+ "obj_layer = Gimp.Layer.new(image, 'Object', width, height, Gimp.ImageType.RGBA_IMAGE, 100, Gimp.LayerMode.NORMAL)",
+ "image.insert_layer(obj_layer, None, 0)",
+
+ # Details layer on top
+ "detail_layer = Gimp.Layer.new(image, 'Details', width, height, Gimp.ImageType.RGBA_IMAGE, 100, Gimp.LayerMode.NORMAL)",
+ "image.insert_layer(detail_layer, None, 0)"]
+```
+
+### Switch Between Layers
+```python
+# Work on different layers
+["# Get all layers",
+ "layers = image.get_layers()",
+
+ "# Work on background (bottom layer)",
+ "bg_drawable = layers[2]",  # Layers are 0=top, higher indices=lower
+ "# ... draw on background ...",
+
+ "# Switch to top layer for details",
+ "detail_drawable = layers[0]",
+ "# ... draw details ...",
+ "Gimp.displays_flush()"]
+```
+
+### Layer Visibility and Opacity
+```python
+# Control layer visibility and blending
+["layer = image.get_layers()[0]",
+
+ "# Hide/show layer",
+ "layer.set_visible(False)",  # Hide
+ "layer.set_visible(True)",   # Show
+
+ "# Adjust opacity (0-100)",
+ "layer.set_opacity(50.0)",   # 50% transparent
+
+ "Gimp.displays_flush()"]
+```
+
+### Fix Mistakes on Specific Layer
+```python
+# Erase part of a layer without affecting others
+["# Select the layer with the mistake",
+ "layer_to_fix = image.get_layers()[1]",
+ "drawable = layer_to_fix",
+
+ "# Select area to clear",
+ "Gimp.Image.select_rectangle(image, Gimp.ChannelOps.REPLACE, x, y, width, height)",
+
+ "# Clear selection (makes it transparent)",
+ "Gimp.Drawable.edit_clear(drawable)",
+
+ "# Redraw correctly",
+ "Gimp.context_set_foreground(correct_color)",
+ "Gimp.Drawable.edit_fill(drawable, Gimp.FillType.FOREGROUND)",
+
+ "Gimp.Selection.none(image)",
+ "Gimp.displays_flush()"]
+```
+
+---
+
+## Advanced: Using Masks and Selections
+
+### Layer Masks for Non-Destructive Editing
+```python
+# Add a mask to control visibility
+["mask = Gimp.LayerMask.new(layer, Gimp.AddMaskType.WHITE)",
+ "layer.add_mask(mask)",
+ "# Now paint on mask to hide/show parts"]
+```
+
+### Selection-Based Operations
+```python
+# Use selections for precise control
+["# Create selection",
+ "Gimp.Image.select_ellipse(image, Gimp.ChannelOps.REPLACE, x, y, w, h)",
+
+ "# Fill selection (NO feathering by default for sharp, clean edges)",
+ "Gimp.Drawable.edit_fill(drawable, Gimp.FillType.FOREGROUND)",
+
+ "# CRITICAL: Clear selection",
+ "Gimp.Selection.none(image)",
+ "Gimp.displays_flush()"]
+
+# Only use feathering when specifically needed for artistic effects:
+# ["Gimp.Selection.feather(image, radius)"]  # Use ONLY if soft edges are explicitly desired
+```
+
+---
+
+## Summary: The Professional Workflow
+
+The key to success with GIMP MCP:
+
+1. **Plan** layer structure first
+2. **Build** incrementally (3-5 operations at a time)
+3. **Validate** after each build phase with `get_image_bitmap()`
+4. **Fix** issues immediately on correct layer
+5. **Continue** only when current phase is correct
+
+**Don't treat GIMP like a single canvas - leverage its professional features!**
+
+Work like a professional digital artist, not like someone with a single paintbrush on a single canvas.