Tools: Fill, Gradient, Shapes
Relevant source files
The following files were used as context for generating this wiki page:
The "Fill, Gradient, and Shapes" tools comprise the core vector-and-pixel hybrid manipulation suite within the Rocreate application. These tools allow users to perform complex area-based operations, ranging from flood-filling connected regions based on color tolerance to rendering geometric primitives and linear or radial gradients. These operations are integrated into the main application controller, KlApp, and are exposed through specific UI components in the toolspace.
Architecturally, these tools follow a pattern where a dedicated "Tool" class (e.g., GradientTool, ShapeTool) handles user input events (down, move, up), while a corresponding "Image Operation" or canvas method performs the actual pixel manipulation or rendering. This separation allows for real-time previewing via a composite layer before the final action is committed to the main canvas.
Sources: src/app/script/app/kl-app.ts:31-64, src/app/script/klecks/kl.ts:104-109
Flood Fill (Paint Bucket)
The Flood Fill tool, commonly referred to as the Paint Bucket, identifies and fills regions of a canvas based on color similarity. It supports both contiguous (connected) and non-contiguous filling modes.
Core Logic and Parameters
The primary entry point for this operation is floodFillBits, which processes a Uint8ClampedArray of RGBA data. The algorithm evaluates pixels against a target color using a user-defined tolerance. If a pixel's RGBA channels fall within the tolerance range of the starting pixel, it is marked for filling.
The tool includes several advanced configuration options:
- Tolerance: Determines how similar a color must be to the target to be included.
- Grow: Expands the resulting filled area by a specified number of pixels.
- Contiguous: If true, only pixels physically connected to the starting point are filled. If false, all matching pixels in the image are filled.
- Sample: Allows sampling from the active layer or all layers combined.
Sources: src/app/script/klecks/image-operations/tests/flood-fill.test.ts:33-145, src/app/script/app/kl-app.ts:544-555
Flood Fill Flow
The following diagram illustrates the data flow when a user initiates a flood fill operation.
Gradient Tool
The Gradient Tool facilitates the creation of smooth color transitions across the canvas. It supports linear, linear-mirror, and radial gradient types.
Implementation Details
The GradientTool class manages the interaction state, capturing the start point (x1, y1) and the current drag point (x2, y2). During the drag operation, KlApp uses a composite layer to render a real-time preview of the gradient without modifying the underlying layer data. Once the user releases the input, the gradient is permanently drawn to the active layer.
| Parameter | Type | Description |
|---|---|---|
type | string | The gradient geometry: 'linear', 'linear-mirror', or 'radial'. |
color1 | TRgb | The primary color of the gradient. |
isReversed | boolean | Reverses the direction of the color transition. |
doSnap | boolean | Snaps the gradient angle to 45-degree increments (often triggered by Shift key). |
Sources: src/app/script/app/kl-app.ts:1146-1175, src/app/script/klecks/kl-types.ts
Gradient Rendering Sequence
This sequence shows the interaction between the UI and the rendering engine during a gradient drag.
Shape Tool
The Shape Tool allows for the precise placement of geometric primitives including rectangles, ellipses, and lines. It functions similarly to the Gradient Tool by utilizing a preview state during interaction.
Tool Configuration
The ShapeUi component provides options for choosing between "Fill" and "Stroke" modes. In stroke mode, users can define the lineWidth. The tool also supports "Outwards" drawing, where the starting point serves as the center of the shape rather than a corner.
Supported Shape Objects
The TShapeToolObject structure defines the properties required for rendering:
- Rectangle: Defined by two points. Supports fixed 1:1 ratio (Square).
- Ellipse: Defined by two points. Supports fixed 1:1 ratio (Circle).
- Line: Defined by start and end points. Supports angle snapping.
Sources: src/app/script/app/kl-app.ts:1182-1215, src/app/script/klecks/kl.ts:104-105
Quick Shape Detection
The application includes a QuickShapeHandler that can detect when a freehand stroke approximates a geometric shape. If the user holds the stylus at the end of a stroke, the system can "snap" the hand-drawn line into a perfect primitive.
Summary of Tool Components
| Component | File Path | Role |
|---|---|---|
GradientTool | gradient-tool.ts | Logic for calculating gradient coordinates and angles. |
ShapeTool | shape-tool.ts | Logic for defining geometric bounds during interaction. |
floodFillBits | flood-fill.ts | The core algorithm for pixel-based region filling. |
FillUi | fill-ui.ts | UI controls for tolerance, grow, and contiguous settings. |
ShapeUi | shape-ui.ts | UI controls for shape type, mode (fill/stroke), and line width. |
Sources: src/app/script/klecks/kl.ts:104-150
The integration of these tools into the KlApp controller ensures that all operations are compatible with the project's undo/redo history system and selection masks. By utilizing a separate composite rendering path for previews, the application maintains high performance even when calculating complex gradients or large-scale shapes.