classical-image-ops

Classical image operations

Use this sub-skill for small, non-neural image transformations in GIMP-ML: inversion, K-means segmentation, palette behavior, and the NumPy/GIMP layer boundary. It is useful both for a novice who needs a safe preflight checklist and for an expert diagnosing shape, channel, or result-layer mismatches.

Scope and boundary

• In scope: current drawable/layer selection, byte-array conversion, image-size checks, RGB/RGBA handling, K-means arguments, palette facts, and result-layer conventions.
• CPU-safe helper reasoning: NumPy array inspection, shape checks, byte-range checks, and pure-array reasoning do not need a model, network, service, or GPU.
• Out of scope: neural plug-ins, training, GIMP installation, remote APIs, model weights, and changes to the live router or service.
• GIMP boundary: the plug-ins use the legacy gimpfu/PDB interface. GIMP and Python 2 are unavailable for the verified host, so a live menu invocation, PDB mutation, and pixel-region write are not verified here. Treat those steps as static-only until tested in a compatible GIMP runtime.

Choose a route

1. Validate an input first. For an .npy or image file, run the bundled adapted helper; it only reads and reports, and does not write by default. See the workflow.
2. Invert a selected drawable. Use the plug-in's Invert registration only when in-place mutation and an undo group are acceptable. The source operation calls the PDB invert procedure on the selected layer; it is not a verified createResultLayer operation. Preserve this exception rather than claiming that it creates a new layer.
3. Segment by color. Select the source layer, confirm it is image-sized, choose a positive cluster count, and decide whether (x, y) is a feature. The K-means route is CPU-oriented but the source does not seed SciPy's initialization, so do not promise reproducible labels without an explicit deterministic wrapper.
4. Inspect palette behavior. The repository's colorpalette plug-in loads its bundled palette image, converts OpenCV BGR to RGB, and opens a separate image named palette. It does not extract colors from the current drawable.
5. Need the exact contract? Open API reference before writing an adapter; open troubleshooting when a run produces no layer, errors on shape, or exhausts memory.

Safe preflight

• Confirm the intended image and active drawable. A drawable is the actual pixel source; the image is the container into which result layers are added.
• Ensure the selected layer has positive height and width and is the same size as its image. Use GIMP's Layer -> Layer to Image Size before K-means when the layer is cropped or offset.
• For K-means, use RGB or RGBA data. RGBA is reduced to RGB by dropping alpha; grayscale, indexed, two-channel, or unexpected multi-channel input is not a supported K-means shape in the source implementation.
• Check that 1 <= clusters <= height * width. Small images cannot support a large K; duplicate colors can also make a requested K ill-conditioned.
• Estimate memory before flattening: K-means materializes one row per pixel and, with position enabled, adds two feature columns. Reduce image size or K when the array is too large for the available RAM.
• Keep byte outputs in the inclusive [0, 255] range. The shared result helper casts to uint8; clipping or validating before that cast avoids silent wrap.

Result conventions

Array-producing plug-ins conventionally convert the result to uint8 bytes, create a layer with the image width and height, write the full pixel region, add the layer at stack position zero, and flush displays. The conventional name is new_output, but it is not a stable identifier. Verify the actual layer after a live run rather than relying on a name.

The shared channelData pattern reads the entire drawable pixel region and reshapes its bytes as (layer.height, layer.width, region.bpp). It preserves an alpha channel until the operation explicitly removes it. It does not repair layer offsets or resample data. A result must have a byte layout compatible with its destination layer; mismatched dimensions or channel count can fail at the pixel-region write.

Determinism and evidence labels

The array validation and conversion guidance is deterministic and CPU-safe. The K-means source calls SciPy kmeans2 with its default initialization and no seed; cluster IDs and borderline assignments may vary. Coordinate features are raw pixel indices, so enabling position changes the feature space, not just the rendering. The color-palette behavior is a static asset-display path, not a verified current-layer extraction algorithm.

Do not infer live GIMP behavior from a successful NumPy/Pillow check. Do not assume CUDA, OpenCV model weights, OpenAI calls, or a running service are needed for these classical routes. For source-derived details and failure handling, follow the linked references.

Linked materials

• Workflows — novice and expert procedures, array-to-layer contracts, and K-means memory guidance.
• API reference — registrations, parameters, helper contracts, supported shapes, and output semantics.
• Troubleshooting — invalid channels, layer-size mismatch, cluster failures, position-feature surprises, and memory/shape errors.
• Bundled array validator — a read-only, adapted helper with --help, explicit input, channel, range, dtype, and size checks.