@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/concepts/design-units.md

@@ -0,0 +1,333 @@
+> This is one page of the CE.SDK Vanilla JS/TS documentation. For a complete overview, see the [Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
+
+**Navigation:** [Concepts](./concepts.md) > [Design Units](./concepts/design-units.md)
+
+---
+
+Control measurement systems for precise physical dimensions—create print-ready
+documents with millimeter or inch units and configurable DPI for export quality.
+
+![Design Units example showing an A4 document configured with millimeter units](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+
+> **Reading time:** 5 minutes
+>
+> **Resources:**
+>
+> - [Download examples](https://github.com/imgly/cesdk-web-examples/archive/refs/tags/release-$UBQ_VERSION$.zip)
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-concepts-design-units-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-concepts-design-units-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-concepts-design-units-browser/)
+
+Design units determine the coordinate system for all layout values in CE.SDK—positions, sizes, and margins. The engine supports three unit types: **Pixel** for screen-based designs, **Millimeter** for metric print dimensions, and **Inch** for imperial print formats.
+
+```typescript file=@cesdk_web_examples/guides-concepts-design-units-browser/browser.ts reference-only
+import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
+
+import {
+  BlurAssetSource,
+  ColorPaletteAssetSource,
+  CropPresetsAssetSource,
+  DemoAssetSources,
+  EffectsAssetSource,
+  FiltersAssetSource,
+  PagePresetsAssetSource,
+  StickerAssetSource,
+  TextAssetSource,
+  TextComponentAssetSource,
+  TypefaceAssetSource,
+  UploadAssetSources,
+  VectorShapeAssetSource
+} from '@cesdk/cesdk-js/plugins';
+import { DesignEditorConfig } from './design-editor/plugin';
+import packageJson from './package.json';
+
+/**
+ * CE.SDK Plugin: Design Units Guide
+ *
+ * Demonstrates working with design units in CE.SDK:
+ * - Understanding unit types (Pixel, Millimeter, Inch)
+ * - Getting and setting the design unit
+ * - Configuring DPI for print output
+ * - Setting up print-ready dimensions
+ */
+class Example implements EditorPlugin {
+  name = packageJson.name;
+
+  version = packageJson.version;
+
+  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
+    if (!cesdk) {
+      throw new Error('CE.SDK instance is required for this plugin');
+    }
+
+    await cesdk.addPlugin(new DesignEditorConfig());
+
+    // Add asset source plugins
+    await cesdk.addPlugin(new BlurAssetSource());
+    await cesdk.addPlugin(new ColorPaletteAssetSource());
+    await cesdk.addPlugin(new CropPresetsAssetSource());
+    await cesdk.addPlugin(
+      new UploadAssetSources({ include: ['ly.img.image.upload'] })
+    );
+    await cesdk.addPlugin(
+      new DemoAssetSources({
+        include: [
+          'ly.img.templates.blank.*',
+          'ly.img.templates.presentation.*',
+          'ly.img.templates.print.*',
+          'ly.img.templates.social.*',
+          'ly.img.image.*'
+        ]
+      })
+    );
+    await cesdk.addPlugin(new EffectsAssetSource());
+    await cesdk.addPlugin(new FiltersAssetSource());
+    await cesdk.addPlugin(new PagePresetsAssetSource());
+    await cesdk.addPlugin(new StickerAssetSource());
+    await cesdk.addPlugin(new TextAssetSource());
+    await cesdk.addPlugin(new TextComponentAssetSource());
+    await cesdk.addPlugin(new TypefaceAssetSource());
+    await cesdk.addPlugin(new VectorShapeAssetSource());
+
+    await cesdk.actions.run('scene.create', {
+      page: { width: 210, height: 297, unit: 'Pixel' }
+    });
+
+    const engine = cesdk.engine;
+
+    // Get the current scene
+    const scene = engine.scene.get();
+    if (scene === null) {
+      throw new Error('No scene available');
+    }
+
+    // Get the current design unit
+    const currentUnit = engine.scene.getDesignUnit();
+    // eslint-disable-next-line no-console
+    console.log('Current design unit:', currentUnit); // 'Pixel' by default
+
+    // Set design unit to Millimeter for print workflow
+    engine.scene.setDesignUnit('Millimeter');
+
+    // Verify the change
+    const newUnit = engine.scene.getDesignUnit();
+    // eslint-disable-next-line no-console
+    console.log('Design unit changed to:', newUnit); // 'Millimeter'
+
+    // Set DPI to 300 for print-quality exports
+    // Higher DPI produces higher resolution output
+    engine.block.setFloat(scene, 'scene/dpi', 300);
+
+    // Verify the DPI setting
+    const dpi = engine.block.getFloat(scene, 'scene/dpi');
+    // eslint-disable-next-line no-console
+    console.log('DPI set to:', dpi); // 300
+
+    // Get the page and set A4 dimensions (210 x 297 mm)
+    const page = engine.block.findByType('page')[0];
+
+    // Verify dimensions
+    const pageWidth = engine.block.getWidth(page);
+    const pageHeight = engine.block.getHeight(page);
+    // eslint-disable-next-line no-console
+    console.log(`Page dimensions: ${pageWidth}mm x ${pageHeight}mm`);
+
+    // Create a text block with millimeter dimensions
+    const textBlock = engine.block.create('text');
+    engine.block.appendChild(page, textBlock);
+
+    // Position text at 20mm from left, 30mm from top
+    engine.block.setPositionX(textBlock, 20);
+    engine.block.setPositionY(textBlock, 30);
+
+    // Set text block size to 170mm x 50mm
+    engine.block.setWidth(textBlock, 170);
+    engine.block.setHeight(textBlock, 50);
+
+    // Add content to the text block
+    engine.block.setString(
+      textBlock,
+      'text/text',
+      'This A4 document uses millimeter units with 300 DPI for print-ready output.'
+    );
+
+    // Demonstrate unit comparison
+    // At 300 DPI: 1 inch = 300 pixels, 1 mm = ~11.81 pixels
+    // eslint-disable-next-line no-console
+    console.log('Unit comparison at 300 DPI:');
+    // eslint-disable-next-line no-console
+    console.log(
+      '- A4 width (210mm) will export as',
+      210 * (300 / 25.4),
+      'pixels'
+    );
+    // eslint-disable-next-line no-console
+    console.log(
+      '- A4 height (297mm) will export as',
+      297 * (300 / 25.4),
+      'pixels'
+    );
+
+    // eslint-disable-next-line no-console
+    console.log(
+      'Design units guide initialized. Scene configured for A4 print output.'
+    );
+  }
+}
+
+export default Example;
+```
+
+This guide covers how to get and set design units, configure DPI for export quality, and set up scenes for specific physical dimensions like A4 paper.
+
+## Understanding Design Units
+
+### Supported Unit Types
+
+CE.SDK supports three design unit types, each suited for different output scenarios:
+
+- **Pixel** — Default unit, ideal for screen-based designs, web graphics, and video content. One unit equals one pixel in the design coordinate space.
+- **Millimeter** — For print designs targeting metric dimensions (A4, A5, business cards). One unit equals one millimeter at the scene's DPI setting.
+- **Inch** — For print designs targeting imperial dimensions (letter, legal, US business cards). One unit equals one inch at the scene's DPI setting.
+
+### Design Unit and DPI Relationship
+
+DPI (dots per inch) determines how physical units convert to pixels during export. At 300 DPI, a 1-inch block exports as 300 pixels wide. Higher DPI values produce higher-resolution exports suitable for professional printing.
+
+For pixel-based scenes, DPI primarily affects font size conversions since font sizes are always specified in points.
+
+## Getting the Current Design Unit
+
+Use `engine.scene.getDesignUnit()` to retrieve the current scene's design unit. This returns one of three values: `'Pixel'`, `'Millimeter'`, or `'Inch'`.
+
+```typescript highlight-get-design-unit
+// Get the current scene
+const scene = engine.scene.get();
+if (scene === null) {
+  throw new Error('No scene available');
+}
+
+// Get the current design unit
+const currentUnit = engine.scene.getDesignUnit();
+// eslint-disable-next-line no-console
+console.log('Current design unit:', currentUnit); // 'Pixel' by default
+```
+
+## Setting the Design Unit
+
+Use `engine.scene.setDesignUnit()` to change the measurement system. When you change the design unit, CE.SDK automatically converts existing layout values to maintain visual appearance.
+
+```typescript highlight-set-design-unit
+// Set design unit to Millimeter for print workflow
+engine.scene.setDesignUnit('Millimeter');
+
+// Verify the change
+const newUnit = engine.scene.getDesignUnit();
+// eslint-disable-next-line no-console
+console.log('Design unit changed to:', newUnit); // 'Millimeter'
+```
+
+## Configuring DPI
+
+Access DPI through the scene's `scene/dpi` property. For print workflows, 300 DPI is the standard for high-quality output.
+
+```typescript highlight-configure-dpi
+// Set DPI to 300 for print-quality exports
+// Higher DPI produces higher resolution output
+engine.block.setFloat(scene, 'scene/dpi', 300);
+
+// Verify the DPI setting
+const dpi = engine.block.getFloat(scene, 'scene/dpi');
+// eslint-disable-next-line no-console
+console.log('DPI set to:', dpi); // 300
+```
+
+DPI affects different aspects depending on the design unit:
+
+- **Physical units (mm, in)**: DPI determines the pixel resolution of exported files
+- **Pixel units**: DPI only affects the conversion of font sizes from points to pixels
+
+## Setting Up Print-Ready Designs
+
+For print workflows, combine `setDesignUnit()` with appropriate DPI and page dimensions. Here's how to set up an A4 document ready for print export:
+
+```typescript highlight-set-page-dimensions
+// Get the page and set A4 dimensions (210 x 297 mm)
+const page = engine.block.findByType('page')[0];
+
+// Verify dimensions
+const pageWidth = engine.block.getWidth(page);
+const pageHeight = engine.block.getHeight(page);
+// eslint-disable-next-line no-console
+console.log(`Page dimensions: ${pageWidth}mm x ${pageHeight}mm`);
+```
+
+## Font Sizes and Design Units
+
+Font sizes are always specified in points (`pt`), regardless of the scene's design unit. The DPI setting affects how points convert to pixels for rendering.
+
+```typescript highlight-create-text-block
+// Create a text block with millimeter dimensions
+const textBlock = engine.block.create('text');
+engine.block.appendChild(page, textBlock);
+
+// Position text at 20mm from left, 30mm from top
+engine.block.setPositionX(textBlock, 20);
+engine.block.setPositionY(textBlock, 30);
+
+// Set text block size to 170mm x 50mm
+engine.block.setWidth(textBlock, 170);
+engine.block.setHeight(textBlock, 50);
+
+// Add content to the text block
+engine.block.setString(
+  textBlock,
+  'text/text',
+  'This A4 document uses millimeter units with 300 DPI for print-ready output.'
+);
+```
+
+When DPI changes, text blocks automatically adjust their rendered size to maintain visual consistency.
+
+## Understanding Export Resolution
+
+The relationship between design units and export resolution is important for print workflows:
+
+```typescript highlight-compare-units
+// Demonstrate unit comparison
+// At 300 DPI: 1 inch = 300 pixels, 1 mm = ~11.81 pixels
+// eslint-disable-next-line no-console
+console.log('Unit comparison at 300 DPI:');
+// eslint-disable-next-line no-console
+console.log('- A4 width (210mm) will export as', 210 * (300 / 25.4), 'pixels');
+// eslint-disable-next-line no-console
+console.log('- A4 height (297mm) will export as', 297 * (300 / 25.4), 'pixels');
+```
+
+At 300 DPI:
+
+- An A4 page (210 × 297 mm) exports as 2480 × 3508 pixels
+- A letter page (8.5 × 11 in) exports as 2550 × 3300 pixels
+
+## Troubleshooting
+
+### Exported Dimensions Don't Match Expected Size
+
+Verify that DPI is set correctly for physical units. At 300 DPI, 1 inch becomes 300 pixels. Check that your design unit matches your target output format.
+
+### Text Appears Wrong Size After Unit Change
+
+Font sizes in points auto-adjust based on DPI. If text looks incorrect, verify the DPI setting matches your workflow requirements.
+
+### Blocks Shift Position After Changing Units
+
+CE.SDK preserves visual appearance during unit conversion. If positions seem unexpected, check the original coordinate values—the numeric values change but visual positions should remain stable.
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS documentation
+- **[Complete Documentation](./llms-full.txt.md)** - Full documentation in one file (for LLMs)
+- **[Web Documentation](./js.md)** - Interactive documentation with examples
+- **[Support](mailto:support@img.ly)** - Contact IMG.LY support