@gradio/imageeditor 0.12.13 → 0.13.0

package/shared/Toolbar.svelte

@@ -0,0 +1,386 @@
+<script lang="ts" context="module">
+	export type Tool = "image" | "draw" | "erase" | "pan";
+	export type Subtool =
+		| "upload"
+		| "paste"
+		| "webcam"
+		| "color"
+		| "size"
+		| "crop"
+		| "remove_background"
+		| null;
+</script>
+
+<script lang="ts">
+	import { createEventDispatcher } from "svelte";
+	import IconButton from "./IconButton.svelte";
+	import {
+		Image,
+		Brush,
+		Erase,
+		Crop,
+		Upload,
+		ImagePaste,
+		Webcam,
+		Circle,
+		Resize,
+		ColorPickerSolid
+	} from "@gradio/icons";
+	import BrushOptions from "./brush/BrushOptions.svelte";
+	import type { Source, Transform } from "./types";
+	import {
+		type Brush as BrushType,
+		type Eraser as EraserType,
+		type ColorTuple
+	} from "./brush/types";
+	import tinycolor from "tinycolor2";
+
+	export let tool: Tool = "image";
+	export let subtool: Subtool = null;
+
+	export let background = false;
+	export let brush_options: BrushType | false;
+	export let selected_size =
+		brush_options && typeof brush_options.default_size === "number"
+			? brush_options.default_size
+			: 25;
+	export let eraser_options: EraserType;
+	export let selected_eraser_size =
+		eraser_options && typeof eraser_options.default_size === "number"
+			? eraser_options.default_size
+			: 25;
+
+	// Handle default_color including potential color-opacity tuple
+	export let selected_color =
+		brush_options &&
+		(() => {
+			const default_color = brush_options.default_color;
+			if (Array.isArray(default_color)) {
+				return default_color[0];
+			}
+			return default_color;
+		})();
+
+	// Set default opacity based on default_color if it's a tuple
+	export let selected_opacity =
+		brush_options &&
+		(() => {
+			const default_color = brush_options.default_color;
+			if (Array.isArray(default_color)) {
+				return default_color[1];
+			}
+			// Check if color string has opacity
+			const color = tinycolor(default_color);
+			if (color.getAlpha() < 1) {
+				return color.getAlpha();
+			}
+			return 1;
+		})();
+
+	export let preview = false;
+	// export let opacity = 1;
+	export let show_brush_color = false;
+	export let show_brush_size = false;
+	export let show_eraser_size = false;
+	export let sources: Source[];
+	export let transforms: Transform[];
+	// Required by the component interface
+	let recent_colors: string[] = [];
+
+	let enable_layers = true;
+	const dispatch = createEventDispatcher<{
+		tool_change: { tool: Tool };
+		subtool_change: {
+			tool: Tool;
+			subtool: Subtool;
+		};
+	}>();
+
+	/**
+	 * Handles tool click events
+	 * @param {Tool} _tool - The selected tool
+	 */
+	function handle_tool_click(e: Event, _tool: Tool): void {
+		e.stopPropagation();
+		dispatch("tool_change", { tool: _tool });
+	}
+
+	/**
+	 * Handles subtool click events
+	 * @param {Event} e - The click event
+	 * @param {Subtool} _subtool - The selected subtool
+	 */
+	function handle_subtool_click(e: Event, _subtool: typeof subtool): void {
+		e.stopPropagation();
+
+		dispatch("subtool_change", { tool, subtool: _subtool });
+	}
+
+	$: show_brush_size = tool === "draw" && subtool === "size";
+	$: show_brush_color = tool === "draw" && subtool === "color";
+	$: show_eraser_size = tool === "erase" && subtool === "size";
+
+	$: can_crop = transforms.includes("crop");
+	$: can_resize = transforms.includes("resize");
+	$: can_upload = sources.includes("upload");
+	$: can_webcam = sources.includes("webcam");
+	$: can_paste = sources.includes("clipboard");
+</script>
+
+<div class="toolbar-wrap">
+	<div class="half-container">
+		{#if sources.length > 0}
+			<IconButton
+				Icon={Image}
+				label="Image"
+				highlight={tool === "image"}
+				on:click={(e) => handle_tool_click(e, "image")}
+				size="medium"
+				padded={false}
+				transparent={true}
+			/>
+		{/if}
+		{#if brush_options}
+			<IconButton
+				Icon={Brush}
+				label="Brush"
+				on:click={(e) => handle_tool_click(e, "draw")}
+				highlight={tool === "draw"}
+				size="medium"
+				padded={false}
+				transparent={true}
+			/>
+		{/if}
+		{#if eraser_options}
+			<IconButton
+				Icon={Erase}
+				label="Erase"
+				on:click={(e) => handle_tool_click(e, "erase")}
+				highlight={tool === "erase"}
+				size="medium"
+				padded={false}
+				transparent={true}
+			/>
+		{/if}
+	</div>
+	<div
+		class="half-container right"
+		class:hide={tool === "pan" ||
+			(tool === "image" && !background && sources.length === 0) ||
+			(tool === "image" && background && transforms.length === 0)}
+	>
+		{#if tool === "image"}
+			{#if background}
+				{#if can_crop}
+					<IconButton
+						Icon={Crop}
+						label="Crop"
+						on:click={(e) => handle_subtool_click(e, "crop")}
+						highlight={subtool === "crop"}
+						size="medium"
+						padded={false}
+						transparent={true}
+						offset={0}
+					/>
+				{/if}
+				{#if can_resize}
+					<IconButton
+						Icon={Resize}
+						label="Resize"
+						on:click={(e) => handle_subtool_click(e, "size")}
+						highlight={subtool === "size"}
+						size="medium"
+						padded={false}
+						transparent={true}
+						offset={0}
+					/>
+				{/if}
+			{:else}
+				{#if can_upload}
+					<IconButton
+						Icon={Upload}
+						label="Upload"
+						on:click={(e) => handle_subtool_click(e, "upload")}
+						highlight={subtool === "upload"}
+						size="medium"
+						padded={false}
+						transparent={true}
+						offset={0}
+					/>
+				{/if}
+				{#if can_paste}
+					<IconButton
+						Icon={ImagePaste}
+						label="Paste"
+						on:click={(e) => handle_subtool_click(e, "paste")}
+						highlight={subtool === "paste"}
+						size="large"
+						padded={false}
+						transparent={true}
+						offset={0}
+					/>
+				{/if}
+				{#if can_webcam}
+					<IconButton
+						Icon={Webcam}
+						label="Webcam"
+						on:click={(e) => handle_subtool_click(e, "webcam")}
+						highlight={subtool === "webcam"}
+						size="medium"
+						padded={false}
+						transparent={true}
+						offset={0}
+					/>
+				{/if}
+			{/if}
+		{/if}
+
+		{#if tool === "draw" && brush_options}
+			<IconButton
+				Icon={ColorPickerSolid}
+				label="Color"
+				color={selected_color}
+				on:click={(e) => handle_subtool_click(e, "color")}
+				size="medium"
+				padded={false}
+				transparent={true}
+				offset={0}
+			/>
+			<IconButton
+				Icon={Circle}
+				label="Brush Size"
+				on:click={(e) => handle_subtool_click(e, "size")}
+				highlight={subtool === "size"}
+				size="medium"
+				padded={false}
+				transparent={true}
+				offset={0}
+			/>
+
+			{#if show_brush_color || show_brush_size}
+				<BrushOptions
+					colors={brush_options.colors}
+					color_mode={brush_options.color_mode}
+					{recent_colors}
+					show_swatch={show_brush_color}
+					show_size={show_brush_size}
+					bind:selected_size
+					bind:selected_color
+					bind:selected_opacity
+					bind:preview
+					on:click_outside={(e) => {
+						e.stopPropagation();
+						preview = false;
+						show_brush_color = false;
+						show_brush_size = false;
+						handle_subtool_click(e, null);
+					}}
+					mode="brush"
+				/>
+			{/if}
+		{/if}
+
+		{#if tool === "erase" && eraser_options}
+			<IconButton
+				Icon={Circle}
+				label="Eraser Size"
+				on:click={(e) => handle_subtool_click(e, "size")}
+				highlight={subtool === "size"}
+				size="medium"
+				padded={false}
+				transparent={true}
+				offset={0}
+			/>
+		{/if}
+		{#if show_eraser_size}
+			<BrushOptions
+				colors={[]}
+				show_swatch={false}
+				show_size={true}
+				bind:selected_size={selected_eraser_size}
+				bind:selected_color
+				bind:selected_opacity
+				bind:preview
+				on:click_outside={(e) => {
+					e.stopPropagation();
+					preview = false;
+					show_eraser_size = false;
+					handle_subtool_click(e, null);
+				}}
+				mode="eraser"
+			/>
+		{/if}
+	</div>
+</div>
+
+<style>
+	.toolbar-wrap {
+		display: inline-flex;
+		flex-direction: column;
+		justify-content: center;
+		align-items: center;
+		position: absolute;
+		left: 15px;
+		right: 0;
+		top: 30%;
+		/* transform: translateY(-50%); */
+		width: 30px;
+		border: 1px solid var(--block-border-color);
+		border-radius: var(--radius-md);
+
+		gap: var(--spacing-sm);
+		z-index: 1000;
+		background-color: var(--block-background-fill);
+	}
+
+	.half-container {
+		flex: 1;
+		display: flex;
+		flex-direction: column;
+		gap: var(--spacing-sm);
+		position: relative;
+	}
+
+	.half-container {
+		width: 100%;
+		padding: var(--spacing-sm) 0;
+	}
+
+	.half-container:last-child {
+		border-top: 1px solid var(--block-border-color);
+	}
+
+	.hide {
+		display: none;
+	}
+
+	/* .toolbar-left,
+	.toolbar-right {
+		display: flex;
+		flex-direction: row;
+		align-items: center;
+		gap: var(--spacing-sm);
+		display: flex;
+		z-index: 1000;
+		border-radius: var(--radius-sm);
+		background-color: #fff;
+		padding: var(--spacing-sm) 0.3rem;
+		width: auto;
+	}
+
+	.toolbar-right {
+		border-left: 0;
+		border-top-left-radius: 0;
+		border-bottom-left-radius: 0;
+	}
+
+	.toolbar-left {
+		border-top-right-radius: 0;
+		border-bottom-right-radius: 0;
+	}
+
+	.toolbar-layers {
+		border-top-left-radius: 0;
+		border-bottom-left-radius: 0;
+	} */
+</style>

package/shared/brush/BRUSH_TOOL.md

@@ -0,0 +1,134 @@
+# Brush Tool Documentation
+
+## Overview
+
+The Brush Tool is a core component of the image editor that allows users to draw and erase on the canvas. It provides a flexible drawing experience with customizable brush size, color, and opacity. This document explains how the brush tool works and the relationships between its components.
+
+## Key Files
+
+- `js/imageeditor/shared/brush/brush.ts`: Main implementation of the brush tool
+- `js/imageeditor/shared/brush/BrushOptions.svelte`: UI controls for brush settings
+- `js/imageeditor/shared/brush/ColorPicker.svelte`: Color selection component
+- `js/imageeditor/shared/brush/ColorSwatch.svelte`: Color swatch component
+- `js/imageeditor/shared/brush/ColorField.svelte`: Color input field component
+- `js/imageeditor/shared/brush/BrushSize.svelte`: Brush size slider component
+- `js/imageeditor/shared/Toolbar.svelte`: Defines tool types and handles tool selection
+- `js/imageeditor/shared/core/editor.ts`: Provides the editor context and tool interface
+
+## Architecture
+
+The brush tool follows the Tool interface defined in `editor.ts`. It integrates with the image editor through the `ImageEditorContext` which provides access to the PIXI.js application, containers, and other utilities.
+
+### Class Structure
+
+The `BrushTool` class implements the `Tool` interface and provides the following functionality:
+
+1. **Drawing and Erasing**: Handles pointer events to draw or erase on the canvas
+2. **Brush Customization**: Allows changing brush size, color, and opacity
+3. **Preview**: Shows a preview of the brush before drawing
+4. **Cursor**: Displays a custom cursor that reflects the current brush settings
+
+### State Management
+
+The brush tool maintains several state variables:
+
+- `state`: Contains the current brush settings (opacity, size, color, mode)
+- `brushSize` and `eraserSize`: Separate size settings for drawing and erasing
+- `isDrawing`: Tracks whether the user is currently drawing
+- `isCursorOverImage`: Tracks whether the cursor is over the image container
+
+### Rendering Pipeline
+
+The brush tool uses multiple PIXI.js textures and containers to manage the drawing process:
+
+1. `left_texture`: Stores the final result that is displayed to the user
+2. `right_texture`: Stores the current state before applying new strokes
+3. `stroke_texture`: Temporarily stores the current stroke being drawn
+4. `displayContainer`: Contains all visual elements of the brush tool
+5. `stroke_container`: Contains the graphics for the current stroke
+6. `erase_graphics`: Used for masking when in erase mode
+
+### Drawing Process
+
+1. **Pointer Down**: Initializes a new stroke, captures the starting position
+2. **Pointer Move**: Draws line segments between points with interpolation for smooth strokes
+3. **Pointer Up**: Commits the current stroke to the canvas
+4. **Commit Stroke**: Merges the temporary stroke with the existing content
+
+### Erasing Process
+
+1. **Pointer Down**: Creates an erase mask at the starting position
+2. **Pointer Move**: Extends the erase mask along the pointer path
+3. **Pointer Up**: Applies the erase mask to the canvas
+4. **Commit Stroke**: Merges the erased content with the existing content
+
+## UI Components
+
+### BrushOptions.svelte
+
+Provides UI controls for:
+- Color selection (via color picker or swatches)
+- Brush size adjustment
+- Recent colors management
+- Brush preview
+
+### Brush Preview
+
+The brush tool can show a preview of the current brush in the center of the screen, which helps users understand the brush size and color before drawing.
+
+## Event Handling
+
+The brush tool sets up the following event listeners:
+
+- `pointerdown`: Starts a new stroke
+- `pointermove`: Continues the current stroke and updates the cursor position
+- `pointerup`/`pointerupoutside`: Ends the current stroke
+- Custom events for checking if the cursor is over the image container
+
+## Integration with Editor
+
+The brush tool integrates with the editor through:
+
+1. **Tool Interface**: Implements the required methods (setup, cleanup, set_tool)
+2. **Context Access**: Uses the ImageEditorContext to access the PIXI.js application and containers
+3. **Tool Switching**: Handles transitions between drawing and erasing modes
+
+## Performance Considerations
+
+The brush tool uses several techniques to maintain performance:
+
+1. **Point Interpolation**: Ensures smooth lines even with fast mouse movements
+2. **Texture Management**: Efficiently manages textures to minimize memory usage
+3. **Cursor Position Checking**: Uses debouncing to avoid excessive updates
+
+## Customization API
+
+The brush tool exposes several methods for customization:
+
+- `setBrushSize(size)`: Sets the brush size
+- `setBrushColor(color)`: Sets the brush color
+- `setBrushOpacity(opacity)`: Sets the brush opacity
+- `set_brush_size(size)`: Sets the brush size (only affects drawing mode)
+- `set_eraser_size(size)`: Sets the eraser size (only affects eraser mode)
+- `set_brush_color(color)`: Sets the brush color (only affects drawing mode)
+- `preview_brush(show)`: Shows or hides the brush preview
+
+## Maintenance Notes
+
+When modifying the brush tool, consider the following:
+
+1. **Texture Cleanup**: Always clean up textures to prevent memory leaks
+2. **Event Listener Management**: Properly add and remove event listeners
+3. **Mode Transitions**: Handle transitions between drawing and erasing modes carefully
+4. **Scale Handling**: Account for the editor scale when drawing and displaying the cursor
+5. **Cursor Visibility**: Manage cursor visibility based on the current tool and cursor position
+
+## Future Improvements
+
+Potential areas for enhancement:
+
+1. **Brush Types**: Add support for different brush types (e.g., airbrush, pencil)
+2. **Pressure Sensitivity**: Integrate with pressure-sensitive devices
+3. **Performance Optimization**: Further optimize for large canvases
+4. **Layer Support**: Improve integration with the layer system
+5. **Undo/Redo**: Enhance undo/redo support for brush strokes 

package/shared/brush/BrushOptions.svelte

@@ -0,0 +1,200 @@
+<script lang="ts">
+	import { createEventDispatcher, tick } from "svelte";
+	import { click_outside } from "../utils/events";
+
+	import { type Brush, type ColorTuple } from "./types";
+	import ColorPicker from "./ColorPicker.svelte";
+	import ColorSwatch from "./ColorSwatch.svelte";
+	import ColorField from "./ColorField.svelte";
+	import BrushSize from "./BrushSize.svelte";
+	import type { ColorInput } from "tinycolor2";
+
+	export let colors: (ColorInput | ColorTuple)[];
+	export let selected_color: any;
+	export let color_mode: Brush["color_mode"] | undefined = undefined;
+	export let recent_colors: (ColorInput | ColorTuple)[] = [];
+	export let selected_size: number;
+	export let selected_opacity: number;
+	export let show_swatch: boolean;
+	export let show_size: boolean;
+	export let mode: "brush" | "eraser" = "brush";
+
+	let color_picker = false;
+	let current_mode: "hex" | "rgb" | "hsl" = "hex";
+	let editing_index: number | null = null;
+
+	const dispatch = createEventDispatcher<{
+		click_outside: void;
+	}>();
+
+	function handle_color_selection(
+		{
+			index,
+			color,
+			opacity
+		}: {
+			index: number | null;
+			color: string | null;
+			opacity?: number;
+		},
+		type: "core" | "user"
+	): void {
+		if (type === "user" && !color) {
+			editing_index = index;
+			color_picker = true;
+		}
+
+		if (!color) return;
+		selected_color = color;
+
+		// Update opacity if provided
+		if (opacity !== undefined) {
+			selected_opacity = opacity;
+		}
+
+		if (type === "core") {
+			color_picker = false;
+		}
+	}
+
+	function handle_color_change(color: string): void {
+		if (editing_index === null) return;
+		recent_colors[editing_index] = color;
+	}
+
+	$: handle_color_change(selected_color);
+	let width = 0;
+	let height = 0;
+
+	function debounce(
+		func: (...args: any[]) => void,
+		delay: number
+	): (...args: any[]) => void {
+		let timeout: NodeJS.Timeout;
+		return function (...args: any[]): void {
+			clearTimeout(timeout);
+			timeout = setTimeout(() => func(...args), delay);
+		};
+	}
+
+	export let preview = false;
+	function handle_preview(): void {
+		if (!preview) {
+			// Show preview immediately when requested
+			preview = true;
+			debounced_close_preview();
+		} else {
+			// Only use debounce when hiding the preview
+			debounced_close_preview();
+		}
+	}
+
+	function handle_close_preview(): void {
+		preview = false;
+	}
+
+	const debounced_close_preview = debounce(handle_close_preview, 1000);
+
+	$: selected_size, selected_color, handle_preview();
+
+	function handle_select(color: string): void {
+		selected_color = color;
+	}
+
+	function handle_add_color(): void {
+		// limit to 5
+		if (recent_colors.length >= 5) {
+			recent_colors.pop();
+		}
+		// check if the color is already in the array
+		if (
+			recent_colors.some((color) => {
+				if (Array.isArray(color)) {
+					return color[0] === selected_color && color[1] === selected_opacity;
+				}
+				return color === selected_color;
+			})
+		) {
+			return;
+		}
+		recent_colors.push([selected_color, selected_opacity]);
+		recent_colors = recent_colors;
+	}
+</script>
+
+<svelte:window bind:innerHeight={height} bind:innerWidth={width} />
+
+<div
+	class="wrap"
+	class:padded={!color_picker}
+	use:click_outside={() => dispatch("click_outside")}
+	class:color_picker
+	class:size_picker={show_size && mode === "brush"}
+	class:eraser_picker={mode === "eraser"}
+>
+	{#if color_mode === "defaults"}
+		{#if color_picker}
+			<ColorPicker
+				bind:color={selected_color}
+				bind:opacity={selected_opacity}
+			/>
+			<ColorField
+				bind:current_mode
+				color={selected_color}
+				on:close={() => (color_picker = false)}
+				on:selected={({ detail }) => handle_select(detail)}
+			/>
+		{/if}
+	{/if}
+	{#if show_swatch}
+		<ColorSwatch
+			bind:color_picker
+			{colors}
+			on:select={({ detail }) => handle_color_selection(detail, "core")}
+			on:edit={({ detail }) => handle_color_selection(detail, "user")}
+			user_colors={color_mode === "defaults" ? recent_colors : null}
+			{selected_color}
+			{current_mode}
+			on:add_color={handle_add_color}
+		/>
+	{/if}
+
+	{#if show_size}
+		<BrushSize max={100} min={1} bind:selected_size />
+	{/if}
+</div>
+
+<style>
+	.wrap {
+		max-width: 230px;
+		/* width: 90%; */
+		position: absolute;
+		display: flex;
+		flex-direction: column;
+		gap: 5px;
+		background: var(--background-fill-secondary);
+		border: 1px solid var(--block-border-color);
+		border-radius: var(--radius-md);
+		box-shadow: 0px 0px 5px 0px rgba(0, 0, 0, 0.1);
+		padding-bottom: var(--size-2);
+		pointer-events: all;
+		cursor: default;
+		z-index: var(--layer-top);
+		overflow: hidden;
+		top: 0;
+
+		transform: translate(35px, -12px);
+	}
+
+	.color_picker {
+		transform: translate(35px, -50%);
+	}
+
+	.size_picker {
+		transform: translate(35px, 18px);
+	}
+
+	.eraser_picker {
+		transform: translate(35px, -7px);
+	}
+</style>