@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/export-save-publish/export/to-raw-data.md

@@ -1,212 +1,142 @@
-> 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) > [Export Media Assets](./export-save-publish/export.md) > [To Raw Data](./export-save-publish/export/to-raw-data.md)
 
 ---
 
-Exporting designs to raw pixel data gives you direct access to uncompressed
-RGBA bytes, enabling custom image processing, GPU texture uploads, and
-integration with advanced graphics pipelines. Unlike compressed formats like
-PNG or JPEG, raw data export provides the pixel buffer without encoding
-overhead, making it ideal for performance-critical applications and scenarios
-where you need to manipulate individual pixels programmatically.
-
-![Export to Raw Data example showing grayscale image processing with export button](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Exporting designs to raw pixel data in Node.js gives you direct access to uncompressed
+RGBA bytes from CE.SDK, enabling custom server-side image processing, automated content pipelines, and
+integration with headless rendering workflows.
 
 > **Reading time:** 15 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)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-export-save-publish-export-to-raw-data-browser/)
-
-```typescript file=@cesdk_web_examples/guides-export-save-publish-export-to-raw-data-browser/src/browser.ts reference-only
-import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
-import packageJson from '../package.json';
-import {
-  BlurAssetSource,
-  CaptionPresetsAssetSource,
-  ColorPaletteAssetSource,
-  CropPresetsAssetSource,
-  DemoAssetSources,
-  EffectsAssetSource,
-  FiltersAssetSource,
-  PagePresetsAssetSource,
-  StickerAssetSource,
-  TextAssetSource,
-  TypefaceAssetSource,
-  UploadAssetSources,
-  VectorShapeAssetSource
-} from '@cesdk/cesdk-js/plugins';
-import { DesignEditorConfig } from '../design-editor/plugin';
-
-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());
-
-    // Load asset source plugins
-    await cesdk.addPlugin(new BlurAssetSource());
-    await cesdk.addPlugin(new CaptionPresetsAssetSource());
-    await cesdk.addPlugin(new ColorPaletteAssetSource());
-    await cesdk.addPlugin(new CropPresetsAssetSource());
-    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 TypefaceAssetSource());
-    await cesdk.addPlugin(new VectorShapeAssetSource());
-    await cesdk.addPlugin(
-      new UploadAssetSources({
-        include: ['ly.img.image.upload']
-      })
-    );
-    await cesdk.addPlugin(
-      new DemoAssetSources({
-        include: ['ly.img.image.*']
-      })
-    );
-    await cesdk.actions.run('scene.create', {
-      page: { width: 800, height: 600, unit: 'Pixel' }
-    });
-
-    const engine = cesdk.engine;
-    const page = engine.block.findByType('page')[0];
-
-    // Set explicit page dimensions
-
-    const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
-
-    // Create a single image block to demonstrate raw data export
-    const imageBlock = await engine.block.addImage(imageUri, {
-      size: { width: 800, height: 600 }
-    });
-    engine.block.appendChild(page, imageBlock);
-    engine.block.setPositionX(imageBlock, 0);
-    engine.block.setPositionY(imageBlock, 0);
-
-    // Add export button to navigation bar
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar', position: 'end' },
-      {
-        id: 'ly.img.actions.navigationBar',
-        children: ['ly.img.exportImage.navigationBar']
-      }
-    );
-
-    // Override the built-in exportDesign action
-    cesdk.actions.register('exportDesign', async () => {
-      // Export to raw pixel data
-      const width = Math.floor(engine.block.getWidth(imageBlock));
-      const height = Math.floor(engine.block.getHeight(imageBlock));
-
-      const blob = await engine.block.export(imageBlock, {
-        mimeType: 'application/octet-stream',
-        targetWidth: width,
-        targetHeight: height
-      });
-
-      // Convert blob to raw pixel array
-      const arrayBuffer = await blob.arrayBuffer();
-      const pixelData = new Uint8Array(arrayBuffer);
-
-      // Apply grayscale processing
-      const processedData = this.toGrayscale(pixelData, width, height);
-
-      // Download processed image
-      await this.downloadProcessedImage(processedData, width, height);
-    });
-  }
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-export-save-publish-export-to-raw-data-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-export-save-publish-export-to-raw-data-server-js)
+
+```typescript file=@cesdk_web_examples/guides-export-save-publish-export-to-raw-data-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+
+// Load environment variables
+config();
+
+/**
+ * CE.SDK Server Guide: Export to Raw Data
+ *
+ * Demonstrates exporting designs to uncompressed RGBA pixel data for custom
+ * image processing in Node.js:
+ * - Exporting blocks to raw pixel data
+ * - Processing pixels with custom algorithms
+ * - Integrating with image processing libraries (Sharp)
+ * - Saving processed data to files
+ */
+
+// Initialize CE.SDK engine in headless mode
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL,
+});
 
-  /**
-   * Convert image to grayscale by averaging RGB channels
-   */
-  private toGrayscale(
-    pixelData: Uint8Array,
-    _width: number,
-    _height: number
-  ): Uint8Array {
-    const result = new Uint8Array(pixelData);
-    for (let i = 0; i < result.length; i += 4) {
-      const avg = Math.round((result[i] + result[i + 1] + result[i + 2]) / 3);
-      result[i] = avg; // R
-      result[i + 1] = avg; // G
-      result[i + 2] = avg; // B
-      // Keep alpha unchanged: result[i + 3]
-    }
-    return result;
+try {
+  // Create a design scene with a single image
+  engine.scene.create('VerticalStack', {
+    page: { size: { width: 800, height: 600 } },
+  });
+  const page = engine.block.findByType('page')[0];
+
+  const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
+  const imageBlock = await engine.block.addImage(imageUri, {
+    size: { width: 800, height: 600 },
+  });
+  engine.block.appendChild(page, imageBlock);
+  engine.block.setPositionX(imageBlock, 0);
+  engine.block.setPositionY(imageBlock, 0);
+
+  // Export to raw pixel data
+  const width = Math.floor(engine.block.getWidth(imageBlock));
+  const height = Math.floor(engine.block.getHeight(imageBlock));
+
+  const blob = await engine.block.export(imageBlock, {
+    mimeType: 'application/octet-stream',
+    targetWidth: width,
+    targetHeight: height,
+  });
+
+  // Convert blob to Buffer for Node.js processing
+  const arrayBuffer = await blob.arrayBuffer();
+  const pixelData = Buffer.from(arrayBuffer);
+
+  // eslint-disable-next-line no-console
+  console.log(`✓ Exported ${pixelData.length} bytes (${width}x${height} RGBA)`);
+
+  // Apply grayscale processing to demonstrate pixel manipulation
+  const processedData = toGrayscale(pixelData);
+
+  // eslint-disable-next-line no-console
+  console.log('✓ Applied grayscale effect');
+
+  // Save processed raw data to file
+  const outputDir = './output';
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
   }
 
-  /**
-   * Convert processed pixel data to PNG and trigger download
-   */
-  private async downloadProcessedImage(
-    pixelData: Uint8Array,
-    width: number,
-    height: number
-  ): Promise<void> {
-    // Create canvas and render pixel data
-    const canvas = document.createElement('canvas');
-    canvas.width = width;
-    canvas.height = height;
-    const ctx = canvas.getContext('2d');
-
-    if (!ctx) {
-      throw new Error('Failed to get canvas context');
-    }
-
-    // Create ImageData from pixel array
-    const imageData = new ImageData(
-      new Uint8ClampedArray(pixelData),
-      width,
-      height
-    );
-    ctx.putImageData(imageData, 0, 0);
-
-    // Convert canvas to blob
-    const blob = await new Promise<Blob>((resolve, reject) => {
-      canvas.toBlob(
-        (blob) => {
-          if (blob) {
-            resolve(blob);
-          } else {
-            reject(new Error('Failed to convert canvas to blob'));
-          }
-        },
-        'image/png',
-        1.0
-      );
-    });
-
-    // Trigger download
-    const url = URL.createObjectURL(blob);
-    const link = document.createElement('a');
-    link.href = url;
-    link.download = 'processed-image.png';
-    link.click();
-
-    // Clean up
-    URL.revokeObjectURL(url);
-  }
+  writeFileSync(`${outputDir}/raw-data.bin`, processedData);
+
+  // eslint-disable-next-line no-console
+  console.log(`✓ Saved raw data to ${outputDir}/raw-data.bin`);
+
+  // Integration with Sharp for converting raw data to PNG
+  // Note: This requires 'sharp' to be installed: npm install sharp
+  //
+  // import sharp from 'sharp';
+  //
+  // await sharp(processedData, {
+  //   raw: {
+  //     width,
+  //     height,
+  //     channels: 4 // RGBA
+  //   }
+  // })
+  //   .png({ compressionLevel: 9 })
+  //   .toFile(`${outputDir}/processed.png`);
+  //
+  // console.log('✓ Saved PNG to output/processed.png');
+} finally {
+  // Always dispose the engine to free resources
+  engine.dispose();
 }
 
-export default Example;
+/**
+ * Convert image to grayscale by averaging RGB channels
+ */
+function toGrayscale(pixelData: Buffer): Buffer {
+  const result = Buffer.from(pixelData);
+  for (let i = 0; i < result.length; i += 4) {
+    const avg = Math.round((result[i] + result[i + 1] + result[i + 2]) / 3);
+    result[i] = avg; // R
+    result[i + 1] = avg; // G
+    result[i + 2] = avg; // B
+    // Keep alpha unchanged: result[i + 3]
+  }
+  return result;
+}
 ```
 
+Unlike compressed formats like PNG or JPEG, raw data export from CE.SDK provides the pixel buffer without encoding overhead, making it ideal for headless server applications, batch processing, and scenarios where you need to manipulate individual pixels programmatically.
+
+This guide covers exporting CE.SDK designs to raw data, processing pixels with custom algorithms, and integrating with image processing libraries like Sharp.
+
 ## When to Use Raw Data Export
 
-Raw pixel data export provides direct access to uncompressed RGBA bytes from CE.SDK, giving you complete control over individual pixels for custom processing workflows.
+Raw pixel data export provides direct access to uncompressed RGBA bytes from CE.SDK in Node.js, giving you complete control over individual pixels for server-side processing workflows.
 
-Use raw data export when you need pixel-level access to exported designs for custom algorithms or integrations. For standard image delivery, use PNG or JPEG exports instead, as they provide compression and are ready to use without additional processing.
+Use raw data export when you need pixel-level access to exported designs for custom algorithms, integrations, or batch processing. For standard image storage or transfer, use PNG or JPEG exports instead, as they provide compression and are universally supported.
 
 ## Understanding Raw Data Format
 
@@ -219,51 +149,55 @@ When you export with `mimeType: 'application/octet-stream'`, CE.SDK returns a Bl
 
 ## How to Export Raw Data
 
-To export a block as raw pixel data, use the `engine.block.export()` method with `mimeType: 'application/octet-stream'`:
+To export a block as raw pixel data in Node.js, use the `engine.block.export()` method with `mimeType: 'application/octet-stream'`:
 
-```typescript highlight-basic-export
-const blob = await engine.block.export(imageBlock, {
-  mimeType: 'application/octet-stream',
-  targetWidth: width,
-  targetHeight: height
-});
+```typescript highlight-export-to-raw-data
+  // Export to raw pixel data
+  const width = Math.floor(engine.block.getWidth(imageBlock));
+  const height = Math.floor(engine.block.getHeight(imageBlock));
+
+  const blob = await engine.block.export(imageBlock, {
+    mimeType: 'application/octet-stream',
+    targetWidth: width,
+    targetHeight: height,
+  });
+
+  // Convert blob to Buffer for Node.js processing
+  const arrayBuffer = await blob.arrayBuffer();
+  const pixelData = Buffer.from(arrayBuffer);
+
+  // eslint-disable-next-line no-console
+  console.log(`✓ Exported ${pixelData.length} bytes (${width}x${height} RGBA)`);
 ```
 
 This returns a Blob containing uncompressed RGBA pixel data that you can process with custom algorithms.
 
 ## Download Exported Data
 
-The example overrides the built-in `exportDesign` action to implement a custom workflow that exports to raw data, processes the pixels, and downloads the result:
-
-```typescript highlight-export-action-body
-// Export to raw pixel data
-const width = Math.floor(engine.block.getWidth(imageBlock));
-const height = Math.floor(engine.block.getHeight(imageBlock));
+After exporting to raw data and processing the pixels, you can save the result to the file system using Node.js file operations:
 
-const blob = await engine.block.export(imageBlock, {
-  mimeType: 'application/octet-stream',
-  targetWidth: width,
-  targetHeight: height
-});
-
-// Convert blob to raw pixel array
-const arrayBuffer = await blob.arrayBuffer();
-const pixelData = new Uint8Array(arrayBuffer);
+```typescript highlight-save-raw-data
+  // Save processed raw data to file
+  const outputDir = './output';
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
 
-// Apply grayscale processing
-const processedData = this.toGrayscale(pixelData, width, height);
+  writeFileSync(`${outputDir}/raw-data.bin`, processedData);
 
-// Download processed image
-await this.downloadProcessedImage(processedData, width, height);
+  // eslint-disable-next-line no-console
+  console.log(`✓ Saved raw data to ${outputDir}/raw-data.bin`);
 ```
 
-This complete workflow demonstrates exporting to raw pixel data, applying grayscale processing, and downloading the processed image as PNG.
+For production use, you'll typically convert the raw pixel data to a standard image format using libraries like Sharp for efficient storage and delivery.
 
 ## Performance Considerations
 
-Raw data export involves trade-offs between flexibility and efficiency:
+Raw data export from CE.SDK involves trade-offs between flexibility and efficiency in server environments:
 
-**Memory Usage**: Raw RGBA data requires 4 bytes per pixel. A 1920×1080 CE.SDK export uses approximately 8.3 MB uncompressed, compared to 1-3 MB for PNG. Reduce memory usage with the `targetWidth` and `targetHeight` export options:
+### Memory Usage
+
+Raw RGBA data requires 4 bytes per pixel. A 1920×1080 CE.SDK export uses approximately 8.3 MB uncompressed, compared to 1-3 MB for PNG. In server environments with limited memory, reduce export resolution using `targetWidth` and `targetHeight` export options:
 
 ```typescript
 const blob = await engine.block.export(blockId, {
@@ -273,31 +207,50 @@ const blob = await engine.block.export(blockId, {
 });
 ```
 
-**Processing Speed**: Operating directly on pixel data from CE.SDK exports is fast because there's no encoding/decoding overhead. However, processing millions of pixels can be time-consuming for complex algorithms. Consider using Web Workers for heavy processing to avoid blocking the main thread.
+Check the maximum export size before exporting large CE.SDK designs:
+
+```typescript
+const maxSize = engine.editor.getMaxExportSize();
+console.log(`Maximum export size: ${maxSize} pixels`);
+```
 
-**When to Use Raw vs. Compressed for CE.SDK Exports**:
+### When to Use Raw vs. Compressed for CE.SDK Exports
 
-- Use raw data when you need custom post-processing before final delivery
-- Use PNG or JPEG for direct downloads from CE.SDK
-- Use raw data for intermediate processing steps in multi-stage pipelines
-- Use compressed formats for final output or network transfer
+- **Use raw data** if you need custom post-processing on CE.SDK exports before delivery
+- **Use PNG or JPEG** if you're just saving CE.SDK designs to disk
+- **Use raw data** for intermediate processing steps in automated pipelines
+- **Use compressed formats** for final output or network transfer
+- **Consider Sharp** for high-performance transformations instead of manual pixel manipulation
+
+## Cleanup
+
+Always dispose of the engine to free resources when you're done processing.
+
+```typescript highlight-cleanup
+// Always dispose the engine to free resources
+engine.dispose();
+```
+
+This ensures all resources are properly cleaned up, preventing memory leaks in long-running server applications.
 
 ## API Reference
 
-| Method                                    | Description                                                                   |
-| ----------------------------------------- | ----------------------------------------------------------------------------- |
-| `engine.block.export()`                   | Exports a block with `mimeType: 'application/octet-stream'` for raw RGBA data |
-| `engine.block.getWidth()`                 | Returns the width of a block in pixels                                        |
-| `engine.block.getHeight()`                | Returns the height of a block in pixels                                       |
-| `Blob.arrayBuffer()`                      | Converts the blob to an ArrayBuffer for raw data access                       |
-| `ImageData()`                             | Creates an ImageData object from a Uint8ClampedArray                          |
-| `CanvasRenderingContext2D.putImageData()` | Paints pixel data onto a canvas                                               |
+| Method                     | Description                                               |
+| -------------------------- | --------------------------------------------------------- |
+| `CreativeEngine.init()`    | Initializes the headless CE.SDK engine for server-side rendering |
+| `engine.block.export()`    | Exports a CE.SDK block with `mimeType: 'application/octet-stream'` for raw RGBA data |
+| `engine.block.getWidth()`  | Returns the width of a CE.SDK block in pixels            |
+| `engine.block.getHeight()` | Returns the height of a CE.SDK block in pixels           |
+| `Blob.arrayBuffer()`       | Converts the blob to an ArrayBuffer for raw data access   |
+| `Buffer.from()`            | Creates a Node.js Buffer from an ArrayBuffer              |
+
+
 
 ---
 
 ## 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