@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/open-the-editor/from-image.md

@@ -1,130 +1,124 @@
-> 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) > [Open the Editor](./open-the-editor.md) > [Create From Image](./open-the-editor/from-image.md)
 
 ---
 
-Create an editable scene from an image file using CE.SDK, with automatic page
-dimensions matching the source image for seamless image editing workflows.
-
-![Create From Image example showing an image loaded into CE.SDK ready for editing](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Create an editable scene from an image file using CE.SDK in headless Node.js
+environments for server-side image processing workflows.
 
 > **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-open-the-editor-from-image-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-open-the-editor-from-image-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-open-the-editor-from-image-browser/)
-
-Starting from an existing image allows you to use the editor for customizing individual assets. The `engine.scene.createFromImage()` method fetches the image, creates a scene with matching dimensions, and sets up pixel-based design units. This differs from loading a saved scene file, as you're creating new editable content from raw image data.
-
-```typescript file=@cesdk_web_examples/guides-open-the-editor-from-image-browser/browser.ts reference-only
-import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
-
-import { DesignEditorConfig } from './design-editor/plugin';
-import packageJson from './package.json';
-
-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());
-    const engine = cesdk.engine;
-
-    // ========================================
-    // Create Scene from Remote Image URL
-    // ========================================
-    // The most common approach: load an image directly from a URL
-    const imageUrl = 'https://img.ly/static/ubq_samples/sample_4.jpg';
-
-    // Create a scene sized to match the image dimensions
-    await engine.scene.createFromImage(imageUrl);
-
-    // The scene is now ready for editing with the image as content
-
-    // ========================================
-    // Working with the Created Scene
-    // ========================================
-    // After creating the scene, access the page for modifications
-    const pages = engine.block.findByType('page');
-    const page = pages[0];
-
-    if (page) {
-      // Get the page dimensions (set from the image)
-      const width = engine.block.getWidth(page);
-      const height = engine.block.getHeight(page);
-      console.log(`Scene created with dimensions: ${width}x${height}`);
-    }
-
-    // Zoom to show the full scene
-    if (page) {
-      await engine.scene.zoomToBlock(page);
-    }
-  }
-}
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-open-the-editor-from-image-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-open-the-editor-from-image-server-js)
 
-export default Example;
-```
+Starting from an existing image allows you to process and transform images on the server. The `engine.scene.createFromImage()` method fetches the image, creates a scene with matching dimensions, and sets up pixel-based design units. This is useful for batch processing, automated image transformations, and server-side rendering pipelines.
 
-## Create Scene from Remote URL
+```typescript file=@cesdk_web_examples/guides-open-the-editor-from-image-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+import { mkdirSync, writeFileSync } from 'fs';
 
-The most common approach is loading an image directly from a URL. Pass the URL to `createFromImage()` to fetch the image and create a scene sized to match its dimensions.
+// Load environment variables
+config();
 
-```typescript highlight-create-from-url
-// The most common approach: load an image directly from a URL
-const imageUrl = 'https://img.ly/static/ubq_samples/sample_4.jpg';
+/**
+ * CE.SDK Server Guide: Create From Image
+ *
+ * Demonstrates how to create an editable scene from an image file
+ * in headless Node.js environments.
+ */
 
-// Create a scene sized to match the image dimensions
-await engine.scene.createFromImage(imageUrl);
+// Initialize CE.SDK engine in headless mode
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: process.env.CESDK_LICENSE, // Optional (trial mode available)
+});
 
-// The scene is now ready for editing with the image as content
-```
+try {
+  mkdirSync('output', { recursive: true });
 
-The method returns a promise that resolves once the image is loaded and the scene is ready for editing. The scene's page dimensions automatically match the image.
+  // ========================================
+  // Create Scene from Remote Image URL
+  // ========================================
+  // The most common approach: load an image directly from a URL
+  const imageUrl = 'https://img.ly/static/ubq_samples/sample_4.jpg';
 
-## Create Scene from HTMLImageElement
+  // Create a scene sized to match the image dimensions
+  await engine.scene.createFromImage(imageUrl);
 
-When you have an image already displayed on your page, extract its `src` attribute and pass it to `createFromImage()`. This is useful when integrating with existing image galleries or previews.
+  // The scene is now ready for editing with the image as content
 
-```typescript
-const element = document.getElementById('source-image') as HTMLImageElement;
-const imageURL = element.src;
-const scene = await engine.scene.createFromImage(imageURL);
+  console.log('✓ Created scene from image URL');
+
+  // ========================================
+  // Working with the Created Scene
+  // ========================================
+  // After creating the scene, access the page for modifications
+  const pages = engine.block.findByType('page');
+  const page = pages[0];
+
+  if (page) {
+    // Get the page dimensions (set from the image)
+    const width = engine.block.getWidth(page);
+    const height = engine.block.getHeight(page);
+    console.log(`Scene dimensions: ${width}x${height}`);
+  }
+
+  // ========================================
+  // Export the Result
+  // ========================================
+  // Export the scene to an image file
+  if (page) {
+    const exportBlob = await engine.block.export(page, {
+      mimeType: 'image/png'
+    });
+    const buffer = Buffer.from(await exportBlob.arrayBuffer());
+    writeFileSync('output/from-image-result.png', buffer);
+    console.log('📄 Exported to: output/from-image-result.png');
+  }
+
+  console.log('\n✓ Create From Image guide completed successfully!');
+} finally {
+  // Always dispose the engine when done
+  engine.dispose();
+  console.log('\n🧹 Engine disposed successfully');
+}
 ```
 
-## Create Scene from Blob
+## Initialize the Engine
 
-For images from file uploads, drag-and-drop, or fetch responses, create an object URL from the blob first. Use `URL.createObjectURL()` to get a URL that `createFromImage()` can load.
+Start by initializing the CE.SDK engine in headless mode. The Node.js package (`@cesdk/node`) provides the same API as the browser version but runs without a visual interface.
 
-```typescript
-const blob = await fetch(imageUrl).then((response) => response.blob());
-const objectURL = URL.createObjectURL(blob);
-const scene = await engine.scene.createFromImage(objectURL);
+```typescript highlight-setup
+// Initialize CE.SDK engine in headless mode
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: process.env.CESDK_LICENSE, // Optional (trial mode available)
+});
 ```
 
-This pattern works with file inputs (`input.files[0]`), clipboard data, and any other blob source.
+## Create Scene from Remote URL
 
-## Create Scene from Canvas Element
+The most common approach is loading an image directly from a URL. Pass the URL to `createFromImage()` to fetch the image and create a scene sized to match its dimensions.
 
-For images rendered on a canvas element, export the canvas to a blob, then create the scene. Use `canvas.toBlob()` for better performance with large images.
+```typescript highlight-create-from-url
+  // The most common approach: load an image directly from a URL
+  const imageUrl = 'https://img.ly/static/ubq_samples/sample_4.jpg';
 
-```typescript
-const canvas = document.getElementById('source-canvas') as HTMLCanvasElement;
-canvas.toBlob(async (blob) => {
-  if (blob) {
-    const objectURL = URL.createObjectURL(blob);
-    const scene = await engine.scene.createFromImage(objectURL);
-  }
-});
+  // Create a scene sized to match the image dimensions
+  await engine.scene.createFromImage(imageUrl);
+
+  // The scene is now ready for editing with the image as content
 ```
 
+The method returns a promise that resolves once the image is loaded and the scene is ready for processing. The scene's page dimensions automatically match the image.
+
 ## Configure Scene Parameters
 
 The `createFromImage()` method accepts optional parameters for DPI, pixel scale factor, and scene layout.
@@ -134,7 +128,7 @@ const scene = await engine.scene.createFromImage(
   imageUrl,
   300, // dpi - defaults to 300
   1, // pixelScaleFactor - defaults to 1
-  'Free' // sceneLayout - defaults to 'Free'
+  'Free', // sceneLayout - defaults to 'Free'
 );
 ```
 
@@ -142,64 +136,100 @@ const scene = await engine.scene.createFromImage(
 - **Pixel Scale Factor**: Accounts for high-DPI displays (defaults to 1)
 - **Scene Layout**: Controls page arrangement - 'Free', 'HorizontalStack', 'VerticalStack', or 'DepthStack' (defaults to 'Free')
 
+## Create Scene from Blob (Server-side)
+
+In server environments, you can fetch an image and create a blob URL for processing.
+
+```typescript
+const response = await fetch(imageUrl);
+const blob = await response.blob();
+const objectURL = URL.createObjectURL(blob);
+const scene = await engine.scene.createFromImage(objectURL);
+```
+
+This pattern is useful when you need to process images fetched from external sources or read from the filesystem.
+
 ## Working with the Created Scene
 
 After creating the scene, use `engine.block.findByType('page')` to access the page. The scene contains a single page with the image as its content.
 
 ```typescript highlight-work-with-scene
-// After creating the scene, access the page for modifications
-const pages = engine.block.findByType('page');
-const page = pages[0];
+  // After creating the scene, access the page for modifications
+  const pages = engine.block.findByType('page');
+  const page = pages[0];
+
+  if (page) {
+    // Get the page dimensions (set from the image)
+    const width = engine.block.getWidth(page);
+    const height = engine.block.getHeight(page);
+    console.log(`Scene dimensions: ${width}x${height}`);
+  }
+```
+
+## Export the Result
 
+After processing, export the scene to an image file using `engine.block.export()`.
+
+```typescript highlight-export
+// Export the scene to an image file
 if (page) {
-  // Get the page dimensions (set from the image)
-  const width = engine.block.getWidth(page);
-  const height = engine.block.getHeight(page);
-  console.log(`Scene created with dimensions: ${width}x${height}`);
+  const exportBlob = await engine.block.export(page, {
+    mimeType: 'image/png'
+  });
+  const buffer = Buffer.from(await exportBlob.arrayBuffer());
+  writeFileSync('output/from-image-result.png', buffer);
+  console.log('📄 Exported to: output/from-image-result.png');
 }
 ```
 
-## Saving Your Work
+## Clean Up Resources
+
+Always dispose of the engine when done to free system resources.
 
-To persist changes after editing, use `engine.scene.saveToString()` or `engine.scene.saveToArchive()`. See [Saving Scenes](./export-save-publish/save.md) for details.
+```typescript highlight-cleanup
+// Always dispose the engine when done
+engine.dispose();
+```
 
 ## Troubleshooting
 
 **Image fails to load**
 
-- Verify the image URL is accessible and returns a valid image
-- Check CORS headers if loading from a different origin
+- Verify the image URL is accessible from your server
+- Check network connectivity and firewall rules
 - Ensure the image format is supported (JPG, PNG, WebP, GIF)
 
-**Scene dimensions don't match expected size**
+**Memory issues with large images**
 
-- The scene uses pixel design units by default
-- DPI affects how dimensions translate to physical measurements
-- Check pixelScaleFactor if rendering appears scaled
+- Process images in batches to manage memory usage
+- Dispose of the engine between batch operations
+- Consider resizing images before processing if output doesn't require full resolution
 
-**Blob URL not working**
+**Export failures**
 
-- Ensure `URL.createObjectURL()` is called before the blob is released
-- Object URLs are only valid within the same document context
-- Consider revoking object URLs when no longer needed to free memory
+- Ensure the output directory exists before writing
+- Check filesystem permissions
+- Verify sufficient disk space for output files
 
 ## API Reference
 
-| Method                         | Description                        |
-| ------------------------------ | ---------------------------------- |
-| `engine.scene.createFromImage` | Create scene from image URL        |
-| `engine.block.findByType`      | Find blocks by type in scene       |
-| `engine.block.getWidth`        | Get block width                    |
-| `engine.block.getHeight`       | Get block height                   |
-| `URL.createObjectURL`          | Create URL from blob (Browser API) |
-| `engine.scene.saveToString`    | Save scene to string format        |
-| `engine.scene.saveToArchive`   | Save scene with embedded assets    |
+| Method                         | Description                     |
+| ------------------------------ | ------------------------------- |
+| `CreativeEngine.init`          | Initialize engine instance      |
+| `engine.scene.createFromImage` | Create scene from image URL     |
+| `engine.block.findByType`      | Find blocks by type in scene    |
+| `engine.block.getWidth`        | Get block width                 |
+| `engine.block.getHeight`       | Get block height                |
+| `engine.block.export`          | Export block to image           |
+| `engine.dispose`               | Clean up engine resources       |
+
+
 
 ---
 
 ## 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