Selection & Transformation

Relevant source files

The following files were used as context for generating this wiki page:

• src/app/script/app/kl-app-select.ts
• src/app/script/klecks/select-tool/select-transform-tool.ts
• src/app/script/klecks/canvas/kl-canvas.ts
• src/app/script/klecks/ui/components/procreate/procreate-layout.ts
• src/app/script/app/kl-app.ts
• src/app/script/klecks/canvas/kl-canvas-transform.ts
• src/app/script/klecks/ui/tool-tabs/select-ui.ts

The Selection & Transformation system provides users with the ability to isolate specific areas of the canvas and perform geometric manipulations on pixel data. This system is integrated into both the classic Klecks interface and the Procreate-style UI, allowing for workflows that include lasso/polygon selection, free transformation, flipping, scaling, and layer-to-layer movement.

Sources: src/app/script/app/kl-app-select.ts:47-58, src/app/script/klecks/ui/components/procreate/procreate-layout.ts:497-515

System Architecture

The selection and transformation logic is coordinated primarily by the KlAppSelect class, which manages the lifecycle of a selection—from initial creation using tools like SelectTool to the application of transformations via SelectTransformTool.

Selection Lifecycle

1. Selection Creation: Users define a multi-polygon area using lasso or polygon shapes. If no selection exists when entering transform mode, the system defaults to the entire canvas bounds.
2. Transformation Mode: Entering this mode triggers a "temp history" state. The system samples the selected area and prepares it for live manipulation.
3. Application: Once the user confirms the transformation, the changes are committed to the KlCanvas, and the temporary history is cleared or merged into the main history stack.

Sources: src/app/script/app/kl-app-select.ts:184-211, src/app/script/app/kl-app-select.ts:386-400

This diagram illustrates the high-level flow from selection creation to final pixel transformation.
Sources: src/app/script/app/kl-app-select.ts:252-384

Core Components

Component	Description
KlAppSelect	Central coordinator linking UI, History, and Canvas for selection events.
SelectTool	Handles the geometry of creating selections (Lasso, Polygon, Rect).
SelectTransformTool	Manages the transformation matrix and provides compositing for live previews.
SelectUi	The interface providing buttons for flipping, scaling, and switching modes.
klCanvasTransformViaSelection	Low-level utility that executes the final pixel move/transform on the canvas.

Sources: src/app/script/app/kl-app-select.ts:60-78, src/app/script/klecks/canvas/kl-canvas-transform.ts

Transformation Logic

Transformations in the system are "non-destructive" during the preview phase. When a user manipulates an object, the system calculates a transformation matrix and updates a "composite" layer on the KlCanvas.

Live Compositing

To provide a 60fps preview, the system uses two types of composites:

• Source Composite: Hides the original pixels in the selected area on the source layer.
• Target Composite: Renders the sampled pixels at the new location/orientation on the target layer.

Sources: src/app/script/app/kl-app-select.ts:104-124

Transformation Parameters

The TSelectTransformTempEntry data structure tracks the state of an ongoing transformation for undo/redo support within the transform session.

export type TSelectTransformTempEntry = {
    type: 'select-transform';
    data: {
        transform: Matrix;
        doClone: boolean;
        targetLayerIndex: number;
        backgroundIsTransparent: boolean;
        algorithm: TInterpolationAlgorithm;
    };
};

Sources: src/app/script/app/kl-app-select.ts:24-34

Procreate-Style Integration

In the Procreate-style UI, selection and transformation are accessed via the top bar and managed through a FloatingPanel. This allows the transformation controls (Flip X/Y, Rotate 45°, Interpolation settings) to persist without obstructing the canvas view.

This sequence shows the interaction between the Procreate-themed UI components and the underlying selection application logic.
Sources: src/app/script/klecks/ui/components/procreate/procreate-layout.ts:505-515, src/app/script/app/kl-app.ts:1535-1540

Implementation Details

Pixel Interpolation

Users can choose between different scaling algorithms during a transformation:

• Smooth: Suitable for most artistic work, providing anti-aliasing.
• Pixelated: Nearest-neighbor scaling, critical for pixel art to maintain sharp edges.

Sources: src/app/script/app/kl-app-select.ts:27-32, src/app/script/app/kl-app-select.ts:369-374

Cloning

The system supports a "Clone" operation within the transform tool. Instead of moving the original pixels, the system duplicates the selectionSample and applies the transformation to the new copy, leaving the original source pixels intact.
Sources: src/app/script/app/kl-app-select.ts:316-350

Conclusion

The Selection & Transformation system is a modular architecture that separates geometric selection logic from pixel manipulation. By using a matrix-based transformation approach and temporary history entries, it ensures that users can perform complex edits with high performance and the ability to revert changes during the preview stage.