@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/colors/conversion.md

@@ -1,4 +1,4 @@
-> 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).
+> This is one page of the CE.SDK Node.js documentation. For a complete overview, see the [Node.js Documentation Index](https://img.ly/docs/cesdk/node.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
 
 **Navigation:** [Guides](./guides.md) > [Colors](./colors.md) > [Color Conversion](./colors/conversion.md)
 
@@ -6,39 +6,25 @@
 
 Convert colors between sRGB, CMYK, and spot color spaces programmatically in CE.SDK.
 
-![Color Conversion example showing color blocks with different color spaces](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
-
 > **Reading time:** 10 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-colors-conversion-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-colors-conversion-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-colors-conversion-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-colors-conversion-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-colors-conversion-server-js)
 
 CE.SDK supports three color spaces: sRGB, CMYK, and SpotColor. When building color interfaces or preparing designs for export, you may need to convert colors between these spaces. The engine handles the mathematical conversion automatically through the `convertColorToColorSpace()` API.
 
-```typescript file=@cesdk_web_examples/guides-colors-conversion-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';
+```typescript file=@cesdk_web_examples/guides-colors-conversion-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { config } from 'dotenv';
+
+// Load environment variables
+config();
 
 // Type guard helpers for identifying color types
 function isRGBAColor(
@@ -59,51 +45,17 @@ function isSpotColor(
   return 'name' in color && 'tint' in color && 'externalReference' in color;
 }
 
-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');
-    }
+async function main() {
+  const engine = await CreativeEngine.init({
+    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+    // license: process.env.CESDK_LICENSE
+  });
 
-    // Enable spot color feature for the UI
-    cesdk.feature.enable('ly.img.spotColor');
-    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: 800, height: 600, unit: 'Pixel' }
+  try {
+    // Create a scene with a page
+    engine.scene.create('VerticalStack', {
+      page: { size: { width: 800, height: 600 } }
     });
-
-    const engine = cesdk.engine;
     const page = engine.block.findByType('page')[0];
 
     const pageWidth = engine.block.getWidth(page);
@@ -114,7 +66,7 @@ class Example implements EditorPlugin {
     const spacing = 30;
     const availableWidth = pageWidth - 2 * margin - 2 * spacing;
     const blockWidth = availableWidth / 3;
-    const blockHeight = pageHeight - 2 * margin - 80; // Leave space for labels
+    const blockHeight = pageHeight - 2 * margin;
 
     // Define a spot color with RGB approximation for screen preview
     engine.editor.setSpotColorRGB('Brand Red', 0.95, 0.25, 0.21);
@@ -185,33 +137,6 @@ class Example implements EditorPlugin {
     engine.block.setPositionX(spotBlock, margin + 2 * (blockWidth + spacing));
     engine.block.setPositionY(spotBlock, margin);
 
-    // Create labels for each color space
-    const labelY = margin + blockHeight + 20;
-    const fontSize = 24;
-
-    const labels = [
-      { text: 'sRGB', x: margin + blockWidth / 2 },
-      { text: 'CMYK', x: margin + blockWidth + spacing + blockWidth / 2 },
-      {
-        text: 'Spot Color',
-        x: margin + 2 * (blockWidth + spacing) + blockWidth / 2
-      }
-    ];
-
-    for (const label of labels) {
-      const textBlock = engine.block.create('//ly.img.ubq/text');
-      engine.block.replaceText(textBlock, label.text);
-      engine.block.setTextFontSize(textBlock, fontSize);
-      engine.block.setWidthMode(textBlock, 'Auto');
-      engine.block.setHeightMode(textBlock, 'Auto');
-      engine.block.appendChild(page, textBlock);
-
-      // Center the label below each block
-      const textWidth = engine.block.getWidth(textBlock);
-      engine.block.setPositionX(textBlock, label.x - textWidth / 2);
-      engine.block.setPositionY(textBlock, labelY);
-    }
-
     // Convert colors to sRGB for screen display
     const srgbColor = engine.block.getColor(srgbFill, 'fill/color/value');
     const cmykColor = engine.block.getColor(cmykFill, 'fill/color/value');
@@ -266,24 +191,48 @@ class Example implements EditorPlugin {
       console.log('Spot color name:', spotColor.name, 'Tint:', spotColor.tint);
     }
 
-    console.log('Color Conversion example loaded successfully');
+    // Export the scene to a PNG file
+    const outputDir = './output';
+    if (!existsSync(outputDir)) {
+      mkdirSync(outputDir, { recursive: true });
+    }
+
+    const blob = await engine.block.export(page, { mimeType: 'image/png' });
+    const buffer = Buffer.from(await blob.arrayBuffer());
+    writeFileSync(`${outputDir}/color-conversion.png`, buffer);
+    console.log('Exported to output/color-conversion.png');
+
+    console.log('Color Conversion example completed successfully');
+  } finally {
+    engine.dispose();
   }
 }
 
-export default Example;
+main().catch(console.error);
 ```
 
 This guide covers how to convert colors between sRGB and CMYK, handle spot color conversions, identify color types with type guards, and understand how tint and alpha values are preserved during conversion.
 
+## Initialize the Engine
+
+Set up the headless Creative Engine for server-side color operations.
+
+```typescript highlight=highlight-setup
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: process.env.CESDK_LICENSE
+});
+```
+
 ## Supported Color Spaces
 
 CE.SDK supports conversion between three color spaces:
 
-| Color Space   | Format                                                | Use Case                   |
-| ------------- | ----------------------------------------------------- | -------------------------- |
-| **sRGB**      | `RGBAColor` with `r`, `g`, `b`, `a` (0.0-1.0)         | Screen display, web output |
-| **CMYK**      | `CMYKColor` with `c`, `m`, `y`, `k`, `tint` (0.0-1.0) | Print workflows            |
-| **SpotColor** | `SpotColor` with `name`, `tint`, `externalReference`  | Specialized printing       |
+| Color Space | Format | Use Case |
+|-------------|--------|----------|
+| **sRGB** | `RGBAColor` with `r`, `g`, `b`, `a` (0.0-1.0) | Screen display, web output |
+| **CMYK** | `CMYKColor` with `c`, `m`, `y`, `k`, `tint` (0.0-1.0) | Print workflows |
+| **SpotColor** | `SpotColor` with `name`, `tint`, `externalReference` | Specialized printing |
 
 ## Setting Up Colors
 
@@ -367,18 +316,24 @@ engine.block.appendChild(page, spotBlock);
 Use `engine.editor.convertColorToColorSpace(color, 'sRGB')` to convert any color to sRGB format. This is useful for displaying color values on screen or when you need RGB components for CSS or other web-based color operations.
 
 ```typescript highlight=highlight-convert-to-srgb
-// Convert colors to sRGB for screen display
-const srgbColor = engine.block.getColor(srgbFill, 'fill/color/value');
-const cmykColor = engine.block.getColor(cmykFill, 'fill/color/value');
-const spotColor = engine.block.getColor(spotFill, 'fill/color/value');
-
-// Convert CMYK to sRGB
-const cmykToRgba = engine.editor.convertColorToColorSpace(cmykColor, 'sRGB');
-console.log('CMYK converted to sRGB:', cmykToRgba);
-
-// Convert Spot color to sRGB (uses defined RGB approximation)
-const spotToRgba = engine.editor.convertColorToColorSpace(spotColor, 'sRGB');
-console.log('Spot color converted to sRGB:', spotToRgba);
+    // Convert colors to sRGB for screen display
+    const srgbColor = engine.block.getColor(srgbFill, 'fill/color/value');
+    const cmykColor = engine.block.getColor(cmykFill, 'fill/color/value');
+    const spotColor = engine.block.getColor(spotFill, 'fill/color/value');
+
+    // Convert CMYK to sRGB
+    const cmykToRgba = engine.editor.convertColorToColorSpace(
+      cmykColor,
+      'sRGB'
+    );
+    console.log('CMYK converted to sRGB:', cmykToRgba);
+
+    // Convert Spot color to sRGB (uses defined RGB approximation)
+    const spotToRgba = engine.editor.convertColorToColorSpace(
+      spotColor,
+      'sRGB'
+    );
+    console.log('Spot color converted to sRGB:', spotToRgba);
 ```
 
 When converting CMYK or spot colors to sRGB, the engine returns an `RGBAColor` object with `r`, `g`, `b`, `a` properties. The tint value from CMYK or spot colors becomes the alpha value in the returned sRGB color.
@@ -388,15 +343,21 @@ When converting CMYK or spot colors to sRGB, the engine returns an `RGBAColor` o
 Use `engine.editor.convertColorToColorSpace(color, 'CMYK')` to convert any color to CMYK format. This is essential for print workflows where you need to ensure colors are in the correct space before export.
 
 ```typescript highlight=highlight-convert-to-cmyk
-// Convert colors to CMYK for print workflows
-const srgbToCmyk = engine.editor.convertColorToColorSpace(srgbColor, 'CMYK');
-console.log('sRGB converted to CMYK:', srgbToCmyk);
-
-// Convert Spot color to CMYK for print output
-// First define CMYK approximation for the spot color
-engine.editor.setSpotColorCMYK('Brand Red', 0.0, 0.85, 0.9, 0.05);
-const spotToCmyk = engine.editor.convertColorToColorSpace(spotColor, 'CMYK');
-console.log('Spot color converted to CMYK:', spotToCmyk);
+    // Convert colors to CMYK for print workflows
+    const srgbToCmyk = engine.editor.convertColorToColorSpace(
+      srgbColor,
+      'CMYK'
+    );
+    console.log('sRGB converted to CMYK:', srgbToCmyk);
+
+    // Convert Spot color to CMYK for print output
+    // First define CMYK approximation for the spot color
+    engine.editor.setSpotColorCMYK('Brand Red', 0.0, 0.85, 0.9, 0.05);
+    const spotToCmyk = engine.editor.convertColorToColorSpace(
+      spotColor,
+      'CMYK'
+    );
+    console.log('Spot color converted to CMYK:', spotToCmyk);
 ```
 
 When converting sRGB colors to CMYK, the alpha value becomes the tint value in the returned CMYK color. For spot colors, define a CMYK approximation with `setSpotColorCMYK()` before converting.
@@ -408,27 +369,27 @@ When converting sRGB colors to CMYK, the alpha value becomes the tint value in t
 Before converting a color, you may need to identify its current color space. CE.SDK provides type guard functions to check the color type.
 
 ```typescript highlight=highlight-type-guards
-// Use type guards to identify color space before conversion
-if (isRGBAColor(srgbColor)) {
-  console.log(
-    'sRGB color components:',
-    `R: ${srgbColor.r}, G: ${srgbColor.g}, B: ${srgbColor.b}, A: ${srgbColor.a}`
-  );
-}
+    // Use type guards to identify color space before conversion
+    if (isRGBAColor(srgbColor)) {
+      console.log(
+        'sRGB color components:',
+        `R: ${srgbColor.r}, G: ${srgbColor.g}, B: ${srgbColor.b}, A: ${srgbColor.a}`
+      );
+    }
 
-if (isCMYKColor(cmykColor)) {
-  console.log(
-    'CMYK color components:',
-    `C: ${cmykColor.c}, M: ${cmykColor.m}, Y: ${cmykColor.y}, K: ${cmykColor.k}, Tint: ${cmykColor.tint}`
-  );
-}
+    if (isCMYKColor(cmykColor)) {
+      console.log(
+        'CMYK color components:',
+        `C: ${cmykColor.c}, M: ${cmykColor.m}, Y: ${cmykColor.y}, K: ${cmykColor.k}, Tint: ${cmykColor.tint}`
+      );
+    }
 
-if (isSpotColor(spotColor)) {
-  console.log('Spot color name:', spotColor.name, 'Tint:', spotColor.tint);
-}
+    if (isSpotColor(spotColor)) {
+      console.log('Spot color name:', spotColor.name, 'Tint:', spotColor.tint);
+    }
 ```
 
-Import the type guards from `@cesdk/cesdk-js`:
+Import the type guards from `@cesdk/node`:
 
 - `isRGBAColor()` - Returns true if the color is an sRGB color
 - `isCMYKColor()` - Returns true if the color is a CMYK color
@@ -438,67 +399,100 @@ Import the type guards from `@cesdk/cesdk-js`:
 
 The tint and alpha values represent transparency in different color spaces:
 
-| Source           | Target | Transformation     |
-| ---------------- | ------ | ------------------ |
-| sRGB (alpha)     | CMYK   | Alpha becomes tint |
-| CMYK (tint)      | sRGB   | Tint becomes alpha |
-| SpotColor (tint) | sRGB   | Tint becomes alpha |
-| SpotColor (tint) | CMYK   | Tint is preserved  |
+| Source | Target | Transformation |
+|--------|--------|----------------|
+| sRGB (alpha) | CMYK | Alpha becomes tint |
+| CMYK (tint) | sRGB | Tint becomes alpha |
+| SpotColor (tint) | sRGB | Tint becomes alpha |
+| SpotColor (tint) | CMYK | Tint is preserved |
+
+## Exporting with Colors
+
+After applying and converting colors, export the scene to a file.
+
+```typescript highlight=highlight-export
+    // Export the scene to a PNG file
+    const outputDir = './output';
+    if (!existsSync(outputDir)) {
+      mkdirSync(outputDir, { recursive: true });
+    }
+
+    const blob = await engine.block.export(page, { mimeType: 'image/png' });
+    const buffer = Buffer.from(await blob.arrayBuffer());
+    writeFileSync(`${outputDir}/color-conversion.png`, buffer);
+    console.log('Exported to output/color-conversion.png');
+```
+
+## Cleanup
+
+Always dispose of the engine when done to release resources.
+
+```typescript highlight=highlight-cleanup
+engine.dispose();
+```
 
 ## Practical Use Cases
 
-### Building a Color Picker
+### Batch Color Conversion
 
-When displaying a color value from a block in a custom color picker, convert to sRGB to show RGB values:
+When processing multiple designs for print, convert all colors to CMYK:
 
 ```typescript
-const fillColor = engine.block.getColor(fillId, 'fill/color/value');
-const rgbaColor = engine.editor.convertColorToColorSpace(fillColor, 'sRGB');
-// Display: R: ${rgbaColor.r * 255}, G: ${rgbaColor.g * 255}, B: ${rgbaColor.b * 255}
+const blocks = engine.block.findAll();
+for (const blockId of blocks) {
+  if (engine.block.hasFill(blockId)) {
+    const fillId = engine.block.getFill(blockId);
+    const color = engine.block.getColor(fillId, 'fill/color/value');
+    const cmykColor = engine.editor.convertColorToColorSpace(color, 'CMYK');
+    console.log(`Block ${blockId} CMYK: C${cmykColor.c} M${cmykColor.m} Y${cmykColor.y} K${cmykColor.k}`);
+  }
+}
 ```
 
-### Export Preparation
+### Color Analysis
 
-Before PDF export for print, verify colors are in CMYK format:
+Analyze colors in a design to report their color space distribution:
 
 ```typescript
 const color = engine.block.getColor(blockId, 'fill/color/value');
-if (!isCMYKColor(color)) {
-  const cmykColor = engine.editor.convertColorToColorSpace(color, 'CMYK');
-  // Log or display the CMYK values
-  console.log(
-    `C: ${cmykColor.c}, M: ${cmykColor.m}, Y: ${cmykColor.y}, K: ${cmykColor.k}`
-  );
+if (isRGBAColor(color)) {
+  console.log('sRGB color detected');
+} else if (isCMYKColor(color)) {
+  console.log('CMYK color detected');
+} else if (isSpotColor(color)) {
+  console.log(`Spot color detected: ${color.name}`);
 }
 ```
 
 ## Troubleshooting
 
-| Issue                                    | Cause                   | Solution                                                                                  |
-| ---------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------- |
-| Spot color converts to unexpected values | Spot color not defined  | Call `setSpotColorRGB()` or `setSpotColorCMYK()` before conversion                        |
-| Colors look different after conversion   | Color gamut differences | Some sRGB colors cannot be exactly represented in CMYK                                    |
-| Type errors with converted colors        | Wrong type assumption   | Use type guards (`isRGBAColor`, `isCMYKColor`, `isSpotColor`) before accessing properties |
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Spot color converts to unexpected values | Spot color not defined | Call `setSpotColorRGB()` or `setSpotColorCMYK()` before conversion |
+| Colors look different after conversion | Color gamut differences | Some sRGB colors cannot be exactly represented in CMYK |
+| Type errors with converted colors | Wrong type assumption | Use type guards (`isRGBAColor`, `isCMYKColor`, `isSpotColor`) before accessing properties |
 
 ## API Reference
 
-| Method                                                      | Description                                                                                             |
-| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Method | Description |
+|--------|-------------|
 | `engine.editor.convertColorToColorSpace(color, colorSpace)` | Convert a color to the target color space. Returns an `RGBAColor` for 'sRGB' or `CMYKColor` for 'CMYK'. |
-| `engine.editor.setSpotColorRGB(name, r, g, b)`              | Define a spot color with an RGB approximation. Components range from 0.0 to 1.0.                        |
-| `engine.editor.setSpotColorCMYK(name, c, m, y, k)`          | Define a spot color with a CMYK approximation. Components range from 0.0 to 1.0.                        |
+| `engine.editor.setSpotColorRGB(name, r, g, b)` | Define a spot color with an RGB approximation. Components range from 0.0 to 1.0. |
+| `engine.editor.setSpotColorCMYK(name, c, m, y, k)` | Define a spot color with a CMYK approximation. Components range from 0.0 to 1.0. |
 
-| Type Guard           | Description                                        |
-| -------------------- | -------------------------------------------------- |
+| Type Guard | Description |
+|------------|-------------|
 | `isRGBAColor(color)` | Returns true if the color is an `RGBAColor` object |
-| `isCMYKColor(color)` | Returns true if the color is a `CMYKColor` object  |
-| `isSpotColor(color)` | Returns true if the color is a `SpotColor` object  |
+| `isCMYKColor(color)` | Returns true if the color is a `CMYKColor` object |
+| `isSpotColor(color)` | Returns true if the color is a `SpotColor` object |
+
+
 
 ---
 
 ## More Resources
 
-- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS documentation
+- **[Node.js Documentation Index](https://img.ly/docs/cesdk/node.md)** - Browse all Node.js 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
+- **[Web Documentation](./node.md)** - Interactive documentation with examples
+- **[Support](mailto:support@img.ly)** - Contact IMG.LY support