Rule of 3rds Composition Guide

invokeai/frontend/web/public/locales/en.json

@@ -580,6 +580,12 @@
                 "title": "Cancel Transform",
                 "desc": "Cancel the pending transform."
             },
+            "settings": {
+                "behavior": "Behavior",
+                "display": "Display",
+                "grid": "Grid",
+                "debug": "Debug"
+            },
             "toggleNonRasterLayers": {
                 "title": "Toggle Non-Raster Layers",
                 "desc": "Show or hide all non-raster layer categories (Control Layers, Inpaint Masks, Regional Guidance)."
@@ -1916,6 +1922,7 @@
         "mergingLayers": "Merging layers",
         "clearHistory": "Clear History",
         "bboxOverlay": "Show Bbox Overlay",
+        "ruleOfThirds": "Show Rule of Thirds",
         "newSession": "New Session",
         "clearCaches": "Clear Caches",
         "recalculateRects": "Recalculate Rects",

invokeai/frontend/web/src/features/controlLayers/components/Settings/CanvasSettingsPopover.tsx

@@ -1,12 +1,14 @@
 import {
   Divider,
   Flex,
+  Icon,
   IconButton,
   Popover,
   PopoverArrow,
   PopoverBody,
   PopoverContent,
   PopoverTrigger,
+  Text,
   useShiftModifier,
 } from '@invoke-ai/ui-library';
 import { CanvasSettingsBboxOverlaySwitch } from 'features/controlLayers/components/Settings/CanvasSettingsBboxOverlaySwitch';
@@ -23,11 +25,12 @@ import { CanvasSettingsOutputOnlyMaskedRegionsCheckbox } from 'features/controlL
 import { CanvasSettingsPreserveMaskCheckbox } from 'features/controlLayers/components/Settings/CanvasSettingsPreserveMaskCheckbox';
 import { CanvasSettingsPressureSensitivityCheckbox } from 'features/controlLayers/components/Settings/CanvasSettingsPressureSensitivity';
 import { CanvasSettingsRecalculateRectsButton } from 'features/controlLayers/components/Settings/CanvasSettingsRecalculateRectsButton';
+import { CanvasSettingsRuleOfThirdsSwitch } from 'features/controlLayers/components/Settings/CanvasSettingsRuleOfThirdsGuideSwitch';
 import { CanvasSettingsShowHUDSwitch } from 'features/controlLayers/components/Settings/CanvasSettingsShowHUDSwitch';
 import { CanvasSettingsShowProgressOnCanvas } from 'features/controlLayers/components/Settings/CanvasSettingsShowProgressOnCanvasSwitch';
 import { memo } from 'react';
 import { useTranslation } from 'react-i18next';
-import { PiGearSixFill } from 'react-icons/pi';
+import { PiCodeFill, PiEyeFill, PiGearSixFill, PiPencilFill, PiSquaresFourFill } from 'react-icons/pi';
 
 export const CanvasSettingsPopover = memo(() => {
   const { t } = useTranslation();
@@ -41,22 +44,57 @@ export const CanvasSettingsPopover = memo(() => {
           alignSelf="stretch"
         />
       </PopoverTrigger>
-      <PopoverContent>
+      <PopoverContent maxW="280px">
         <PopoverArrow />
         <PopoverBody>
           <Flex direction="column" gap={2}>
-            <CanvasSettingsInvertScrollCheckbox />
-            <CanvasSettingsPreserveMaskCheckbox />
-            <CanvasSettingsClipToBboxCheckbox />
-            <CanvasSettingsOutputOnlyMaskedRegionsCheckbox />
-            <CanvasSettingsSnapToGridCheckbox />
-            <CanvasSettingsPressureSensitivityCheckbox />
-            <CanvasSettingsShowProgressOnCanvas />
-            <CanvasSettingsIsolatedStagingPreviewSwitch />
-            <CanvasSettingsIsolatedLayerPreviewSwitch />
-            <CanvasSettingsDynamicGridSwitch />
-            <CanvasSettingsBboxOverlaySwitch />
-            <CanvasSettingsShowHUDSwitch />
+            {/* Behavior Settings */}
+            <Flex direction="column" gap={1}>
+              <Flex align="center" gap={2}>
+                <Icon as={PiPencilFill} boxSize={4} />
+                <Text fontWeight="bold" fontSize="sm" color="base.100">
+                  {t('hotkeys.canvas.settings.behavior')}
+                </Text>
+              </Flex>
+              <CanvasSettingsInvertScrollCheckbox />
+              <CanvasSettingsPressureSensitivityCheckbox />
+              <CanvasSettingsPreserveMaskCheckbox />
+              <CanvasSettingsClipToBboxCheckbox />
+              <CanvasSettingsOutputOnlyMaskedRegionsCheckbox />
+            </Flex>
+
+            <Divider />
+
+            {/* Display Settings */}
+            <Flex direction="column" gap={1}>
+              <Flex align="center" gap={2} color="base.200">
+                <Icon as={PiEyeFill} boxSize={4} />
+                <Text fontWeight="bold" fontSize="sm">
+                  {t('hotkeys.canvas.settings.display')}
+                </Text>
+              </Flex>
+              <CanvasSettingsShowProgressOnCanvas />
+              <CanvasSettingsIsolatedStagingPreviewSwitch />
+              <CanvasSettingsIsolatedLayerPreviewSwitch />
+              <CanvasSettingsBboxOverlaySwitch />
+              <CanvasSettingsShowHUDSwitch />
+            </Flex>
+
+            <Divider />
+
+            {/* Grid Settings */}
+            <Flex direction="column" gap={1}>
+              <Flex align="center" gap={2} color="base.200">
+                <Icon as={PiSquaresFourFill} boxSize={4} />
+                <Text fontWeight="bold" fontSize="sm">
+                  {t('hotkeys.canvas.settings.grid')}
+                </Text>
+              </Flex>
+              <CanvasSettingsSnapToGridCheckbox />
+              <CanvasSettingsDynamicGridSwitch />
+              <CanvasSettingsRuleOfThirdsSwitch />
+            </Flex>
+
             <DebugSettings />
           </Flex>
         </PopoverBody>
@@ -68,6 +106,7 @@ export const CanvasSettingsPopover = memo(() => {
 CanvasSettingsPopover.displayName = 'CanvasSettingsPopover';
 
 const DebugSettings = () => {
+  const { t } = useTranslation();
   const shift = useShiftModifier();
 
   if (!shift) {
@@ -77,10 +116,18 @@ const DebugSettings = () => {
   return (
     <>
       <Divider />
-      <CanvasSettingsClearCachesButton />
-      <CanvasSettingsRecalculateRectsButton />
-      <CanvasSettingsLogDebugInfoButton />
-      <CanvasSettingsClearHistoryButton />
+      <Flex direction="column" gap={1}>
+        <Flex align="center" gap={2} color="base.200">
+          <Icon as={PiCodeFill} boxSize={4} />
+          <Text fontWeight="bold" fontSize="sm">
+            {t('hotkeys.canvas.settings.debug')}
+          </Text>
+        </Flex>
+        <CanvasSettingsClearCachesButton />
+        <CanvasSettingsRecalculateRectsButton />
+        <CanvasSettingsLogDebugInfoButton />
+        <CanvasSettingsClearHistoryButton />
+      </Flex>
     </>
   );
 };

invokeai/frontend/web/src/features/controlLayers/components/Settings/CanvasSettingsRuleOfThirdsGuideSwitch.tsx

@@ -0,0 +1,25 @@
+import { FormControl, FormLabel, Switch } from '@invoke-ai/ui-library';
+import { useAppDispatch, useAppSelector } from 'app/store/storeHooks';
+import { selectRuleOfThirds, settingsRuleOfThirdsToggled } from 'features/controlLayers/store/canvasSettingsSlice';
+import { memo, useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export const CanvasSettingsRuleOfThirdsSwitch = memo(() => {
+  const { t } = useTranslation();
+  const dispatch = useAppDispatch();
+  const ruleOfThirds = useAppSelector(selectRuleOfThirds);
+  const onChange = useCallback(() => {
+    dispatch(settingsRuleOfThirdsToggled());
+  }, [dispatch]);
+
+  return (
+    <FormControl>
+      <FormLabel m={0} flexGrow={1}>
+        {t('controlLayers.ruleOfThirds')}
+      </FormLabel>
+      <Switch size="sm" isChecked={ruleOfThirds} onChange={onChange} />
+    </FormControl>
+  );
+});
+
+CanvasSettingsRuleOfThirdsSwitch.displayName = 'CanvasSettingsRuleOfThirdsSwitch';

invokeai/frontend/web/src/features/controlLayers/konva/CanvasCompositionGuideModule.ts

@@ -0,0 +1,150 @@
+import type { CanvasManager } from 'features/controlLayers/konva/CanvasManager';
+import { CanvasModuleBase } from 'features/controlLayers/konva/CanvasModuleBase';
+import { getPrefixedId } from 'features/controlLayers/konva/util';
+import { selectRuleOfThirds } from 'features/controlLayers/store/canvasSettingsSlice';
+import { selectBbox } from 'features/controlLayers/store/selectors';
+import Konva from 'konva';
+import type { Logger } from 'roarr';
+
+/**
+ * Renders the rule of thirds composition guide overlay on the canvas.
+ * The guide shows a 3x3 grid within the bounding box to help with composition.
+ */
+export class CanvasCompositionGuideModule extends CanvasModuleBase {
+  readonly type = 'composition_guide';
+  readonly id: string;
+  readonly path: string[];
+  readonly parent: CanvasManager;
+  readonly manager: CanvasManager;
+  readonly log: Logger;
+
+  subscriptions: Set<() => void> = new Set();
+
+  /**
+   * The Konva objects that make up the composition guide:
+   * - A group to hold all the guide lines
+   * - Individual line objects for the rule of thirds grid
+   */
+  konva: {
+    group: Konva.Group;
+    verticalLine1: Konva.Line;
+    verticalLine2: Konva.Line;
+    horizontalLine1: Konva.Line;
+    horizontalLine2: Konva.Line;
+  };
+
+  constructor(manager: CanvasManager) {
+    super();
+    this.id = getPrefixedId(this.type);
+    this.parent = manager;
+    this.manager = manager;
+    this.path = this.manager.buildPath(this);
+    this.log = this.manager.buildLogger(this);
+
+    this.log.debug('Creating composition guide module');
+
+    this.konva = {
+      group: new Konva.Group({
+        name: `${this.type}:group`,
+        listening: false,
+        perfectDrawEnabled: false,
+      }),
+      verticalLine1: new Konva.Line({
+        name: `${this.type}:vertical_line_1`,
+        listening: false,
+        stroke: 'hsl(220 12% 90% / 0.9)',
+        strokeWidth: 1,
+        strokeScaleEnabled: false,
+        perfectDrawEnabled: false,
+        dash: [5, 5],
+      }),
+      verticalLine2: new Konva.Line({
+        name: `${this.type}:vertical_line_2`,
+        listening: false,
+        stroke: 'hsl(220 12% 90% / 0.9)',
+        strokeWidth: 1,
+        strokeScaleEnabled: false,
+        perfectDrawEnabled: false,
+        dash: [5, 5],
+      }),
+      horizontalLine1: new Konva.Line({
+        name: `${this.type}:horizontal_line_1`,
+        listening: false,
+        stroke: 'hsl(220 12% 90% / 0.9)',
+        strokeWidth: 1,
+        strokeScaleEnabled: false,
+        perfectDrawEnabled: false,
+        dash: [5, 5],
+      }),
+      horizontalLine2: new Konva.Line({
+        name: `${this.type}:horizontal_line_2`,
+        listening: false,
+        stroke: 'hsl(220 12% 90% / 0.9)',
+        strokeWidth: 1,
+        strokeScaleEnabled: false,
+        perfectDrawEnabled: false,
+        dash: [5, 5],
+      }),
+    };
+
+    this.konva.group.add(this.konva.verticalLine1);
+    this.konva.group.add(this.konva.verticalLine2);
+    this.konva.group.add(this.konva.horizontalLine1);
+    this.konva.group.add(this.konva.horizontalLine2);
+
+    // Listen for changes to the rule of thirds guide setting
+    this.subscriptions.add(this.manager.stateApi.createStoreSubscription(selectRuleOfThirds, this.render));
+
+    // Listen for changes to the bbox to update guide positioning
+    this.subscriptions.add(this.manager.stateApi.createStoreSubscription(selectBbox, this.render));
+  }
+
+  initialize = () => {
+    this.log.debug('Initializing composition guide module');
+    this.render();
+  };
+
+  /**
+   * Renders the composition guide. The guide is only visible when the setting is enabled.
+   */
+  render = () => {
+    const ruleOfThirds = this.manager.stateApi.getSettings().ruleOfThirds;
+    const { x, y, width, height } = this.manager.stateApi.runSelector(selectBbox).rect;
+
+    this.konva.group.visible(ruleOfThirds);
+
+    if (!ruleOfThirds) {
+      return;
+    }
+
+    // Calculate the thirds positions of the bounding box
+    const oneThirdX = x + width / 3;
+    const twoThirdsX = x + (2 * width) / 3;
+    const oneThirdY = y + height / 3;
+    const twoThirdsY = y + (2 * height) / 3;
+
+    // Update the vertical lines (divide the bbox into thirds vertically)
+    this.konva.verticalLine1.points([oneThirdX, y, oneThirdX, y + height]);
+    this.konva.verticalLine2.points([twoThirdsX, y, twoThirdsX, y + height]);
+
+    // Update the horizontal lines (divide the bbox into thirds horizontally)
+    this.konva.horizontalLine1.points([x, oneThirdY, x + width, oneThirdY]);
+    this.konva.horizontalLine2.points([x, twoThirdsY, x + width, twoThirdsY]);
+  };
+
+  destroy = () => {
+    this.log.debug('Destroying composition guide module');
+    this.subscriptions.forEach((unsubscribe) => unsubscribe());
+    this.subscriptions.clear();
+    this.konva.group.destroy();
+  };
+
+  repr = () => {
+    return {
+      id: this.id,
+      type: this.type,
+      path: this.path,
+      visible: this.konva.group.visible(),
+    };
+  };
+}

invokeai/frontend/web/src/features/controlLayers/konva/CanvasManager.ts

@@ -32,6 +32,7 @@ import { assert } from 'tsafe';
 import type { JsonObject } from 'type-fest';
 
 import { CanvasBackgroundModule } from './CanvasBackgroundModule';
+import { CanvasCompositionGuideModule } from './CanvasCompositionGuideModule';
 import { CanvasStateApiModule } from './CanvasStateApiModule';
 
 export class CanvasManager extends CanvasModuleBase {
@@ -61,6 +62,7 @@ export class CanvasManager extends CanvasModuleBase {
   compositor: CanvasCompositorModule;
   tool: CanvasToolModule;
   stagingArea: CanvasStagingAreaModule;
+  compositionGuide: CanvasCompositionGuideModule;
 
   konva: {
     previewLayer: Konva.Layer;
@@ -101,6 +103,7 @@ export class CanvasManager extends CanvasModuleBase {
 
     this.compositor = new CanvasCompositorModule(this);
     this.stagingArea = new CanvasStagingAreaModule(this);
+    this.compositionGuide = new CanvasCompositionGuideModule(this);
 
     this.$isBusy = computed(
       [
@@ -129,6 +132,7 @@ export class CanvasManager extends CanvasModuleBase {
     // Must add in this order for correct z-index
     this.konva.previewLayer.add(this.stagingArea.konva.group);
     this.konva.previewLayer.add(this.tool.konva.group);
+    this.konva.previewLayer.add(this.compositionGuide.konva.group);
   }
 
   getAdapter = <T extends CanvasEntityType = CanvasEntityType>(
@@ -236,6 +240,7 @@ export class CanvasManager extends CanvasModuleBase {
       this.entityRenderer,
       this.compositor,
       this.stage,
+      this.compositionGuide,
     ];
   };
 
@@ -281,6 +286,7 @@ export class CanvasManager extends CanvasModuleBase {
       entityRenderer: this.entityRenderer.repr(),
       compositor: this.compositor.repr(),
       stage: this.stage.repr(),
+      compositionGuide: this.compositionGuide.repr(),
     };
   };