@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/filters-and-effects/blur.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) > [Filters and Effects](./filters-and-effects.md) > [Apply Blur](./filters-and-effects/blur.md)
 
@@ -7,155 +7,188 @@
 Apply blur effects to design elements using CE.SDK's dedicated blur system for
 creating depth, focus, and atmospheric effects.
 
-![Blur Effects example showing an image with radial blur applied](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
-
 > **Reading time:** 8 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-filters-and-effects-blur-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-filters-and-effects-blur-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-filters-and-effects-blur-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-filters-and-effects-blur-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-filters-and-effects-blur-server-js)
 
 Unlike general effects that stack on elements, blur is a dedicated feature with its own API methods. Each block supports exactly one blur at a time, though the same blur instance can be shared across multiple blocks. CE.SDK provides four blur types: **uniform** for consistent softening, **linear** and **mirrored** for gradient-based effects along axes, and **radial** for circular focal points.
 
-```typescript file=@cesdk_web_examples/guides-filters-and-effects-blur-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';
-
-class BlurPlugin implements EditorPlugin {
-  name = 'BlurPlugin';
-
-  version = '1.0.0';
-
-  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
-    if (!cesdk) {
-      throw new Error('CE.SDK instance is required for this plugin');
-    }
-
-    const engine = cesdk.engine;
-    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: {
-        sourceId: 'ly.img.page.presets',
-        assetId: 'ly.img.page.presets.print.iso.a6.landscape'
-      }
-    });
-
-    const page = engine.block.findByType('page')[0];
-
-    // Get page dimensions to position content correctly
-    const pageWidth = engine.block.getWidth(page);
-    const pageHeight = engine.block.getHeight(page);
-
-    if (!engine.block.supportsBlur(page)) {
-      console.log('Block does not support blur');
-      return;
-    }
-
-    // Create an image block
-    const imageBlock = engine.block.create('graphic');
-    engine.block.setShape(imageBlock, engine.block.createShape('rect'));
-    const imageFill = engine.block.createFill('image');
-    engine.block.setFill(imageBlock, imageFill);
-    engine.block.setString(
-      imageFill,
-      'fill/image/imageFileURI',
-      'https://img.ly/static/ubq_samples/sample_1.jpg'
-    );
-
-    // Position image to fill the page
-    engine.block.setWidth(imageBlock, pageWidth);
-    engine.block.setHeight(imageBlock, pageHeight);
-    engine.block.setPositionX(imageBlock, 0);
-    engine.block.setPositionY(imageBlock, 0);
-
-    engine.block.appendChild(page, imageBlock);
-
-    const blur = engine.block.createBlur('//ly.img.ubq/blur/radial');
-
-    engine.block.setFloat(blur, 'blur/radial/blurRadius', 40);
-    engine.block.setFloat(blur, 'blur/radial/radius', 100);
-    engine.block.setFloat(blur, 'blur/radial/gradientRadius', 80);
-    engine.block.setFloat(blur, 'blur/radial/x', 0.5);
-    engine.block.setFloat(blur, 'blur/radial/y', 0.5);
-
-    engine.block.setBlur(imageBlock, blur);
-    engine.block.setBlurEnabled(imageBlock, true);
-
-    const appliedBlur = engine.block.getBlur(imageBlock);
-    const isEnabled = engine.block.isBlurEnabled(imageBlock);
-    const blurType = engine.block.getType(appliedBlur);
-    console.log('Blur type:', blurType, 'Enabled:', isEnabled);
-
-    engine.block.setBlurEnabled(imageBlock, false);
-    const nowEnabled = engine.block.isBlurEnabled(imageBlock);
-    console.log('Blur now enabled:', nowEnabled);
-    engine.block.setBlurEnabled(imageBlock, true);
+```typescript file=@cesdk_web_examples/guides-filters-and-effects-blur-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: Blur Effects
+ *
+ * Demonstrates applying blur effects to design elements:
+ * - Checking blur support
+ * - Creating and applying blur effects
+ * - Configuring blur parameters for different types
+ * - Enabling/disabling blur
+ * - Sharing blur across blocks
+ * - Exporting results
+ */
+
+// 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)
+});
+
+try {
+  // Create a design scene with specific page dimensions
+  engine.scene.create('VerticalStack', {
+    page: { size: { width: 800, height: 600 } }
+  });
+  const page = engine.block.findByType('page')[0];
+
+  // Sample image URL for demonstrations
+  const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
+
+  // Create an image block to check blur support
+  const sampleBlock = await engine.block.addImage(imageUri, {
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, sampleBlock);
+
+  // Check if the block supports blur - graphic blocks with shapes support blur
+  const supportsBlur = engine.block.supportsBlur(sampleBlock);
+  console.log('Block supports blur:', supportsBlur);
+
+  // Create a radial blur effect
+  const blur = engine.block.createBlur('//ly.img.ubq/blur/radial');
+
+  // Configure radial blur parameters
+  engine.block.setFloat(blur, 'blur/radial/blurRadius', 40);
+  engine.block.setFloat(blur, 'blur/radial/radius', 100);
+  engine.block.setFloat(blur, 'blur/radial/gradientRadius', 80);
+  engine.block.setFloat(blur, 'blur/radial/x', 0.5);
+  engine.block.setFloat(blur, 'blur/radial/y', 0.5);
+
+  // Apply the blur to the image block
+  engine.block.setBlur(sampleBlock, blur);
+  engine.block.setBlurEnabled(sampleBlock, true);
+
+  // Access the applied blur and its properties
+  const appliedBlur = engine.block.getBlur(sampleBlock);
+  const isEnabled = engine.block.isBlurEnabled(sampleBlock);
+  const blurType = engine.block.getType(appliedBlur);
+  console.log('Blur type:', blurType, 'Enabled:', isEnabled);
+
+  // Disable blur temporarily
+  engine.block.setBlurEnabled(sampleBlock, false);
+  console.log('Blur disabled:', !engine.block.isBlurEnabled(sampleBlock));
+
+  // Re-enable for final export
+  engine.block.setBlurEnabled(sampleBlock, true);
+
+  // Create additional blocks to demonstrate different blur types
+  // Create a uniform blur for even softening
+  const uniformBlock = await engine.block.addImage(imageUri, {
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, uniformBlock);
+  engine.block.setPositionX(uniformBlock, 350);
+
+  const uniformBlur = engine.block.createBlur('//ly.img.ubq/blur/uniform');
+  engine.block.setFloat(uniformBlur, 'blur/uniform/intensity', 0.6);
+  engine.block.setBlur(uniformBlock, uniformBlur);
+  engine.block.setBlurEnabled(uniformBlock, true);
+
+  // Create a linear blur for gradient effect
+  const linearBlock = await engine.block.addImage(imageUri, {
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, linearBlock);
+  engine.block.setPositionY(linearBlock, 275);
+
+  const linearBlur = engine.block.createBlur('//ly.img.ubq/blur/linear');
+  engine.block.setFloat(linearBlur, 'blur/linear/blurRadius', 35);
+  engine.block.setFloat(linearBlur, 'blur/linear/x1', 0);
+  engine.block.setFloat(linearBlur, 'blur/linear/y1', 0);
+  engine.block.setFloat(linearBlur, 'blur/linear/x2', 1);
+  engine.block.setFloat(linearBlur, 'blur/linear/y2', 1);
+  engine.block.setBlur(linearBlock, linearBlur);
+  engine.block.setBlurEnabled(linearBlock, true);
+
+  // Create a mirrored blur for tilt-shift effect
+  const mirroredBlock = await engine.block.addImage(imageUri, {
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, mirroredBlock);
+  engine.block.setPositionX(mirroredBlock, 350);
+  engine.block.setPositionY(mirroredBlock, 275);
+
+  const mirroredBlur = engine.block.createBlur('//ly.img.ubq/blur/mirrored');
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/blurRadius', 30);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/gradientSize', 50);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/size', 75);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/x1', 0);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/y1', 0.3);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/x2', 1);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/y2', 0.7);
+  engine.block.setBlur(mirroredBlock, mirroredBlur);
+  engine.block.setBlurEnabled(mirroredBlock, true);
+
+  // Export the scene to PNG
+  const blob = await engine.block.export(page, { mimeType: 'image/png' });
+  const buffer = Buffer.from(await blob.arrayBuffer());
+
+  // Ensure output directory exists
+  if (!existsSync('output')) {
+    mkdirSync('output');
   }
-}
 
-export default BlurPlugin;
+  // Save to file
+  writeFileSync('output/blur-effects.png', buffer);
+  console.log('Exported to output/blur-effects.png');
+} finally {
+  engine.dispose();
+}
 ```
 
 This guide covers how to apply blur effects programmatically using the block API.
 
 ## Programmatic Blur Application
 
+### Initialize CE.SDK
+
+For applications that need to apply blur programmatically—whether for automation, batch processing, or dynamic content generation—we start by setting up CE.SDK with the proper configuration.
+
+```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 initializes the CE.SDK engine in headless mode, giving you full API access to the blur system without UI dependencies.
+
 ### Check Blur Support
 
 Before applying blur to a block, verify it supports blur effects. Graphic blocks with shapes and pages support blur.
 
 ```typescript highlight-check-blur-support
-if (!engine.block.supportsBlur(page)) {
-  console.log('Block does not support blur');
-  return;
-}
+  // Create an image block to check blur support
+  const sampleBlock = await engine.block.addImage(imageUri, {
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, sampleBlock);
+
+  // Check if the block supports blur - graphic blocks with shapes support blur
+  const supportsBlur = engine.block.supportsBlur(sampleBlock);
+  console.log('Block supports blur:', supportsBlur);
 ```
 
 Always check support before creating and applying blur to avoid errors.
@@ -165,6 +198,7 @@ Always check support before creating and applying blur to avoid errors.
 Create a blur instance using `createBlur()` with a blur type, then attach it to a block using `setBlur()`. Enable the blur with `setBlurEnabled()`.
 
 ```typescript highlight-create-blur
+// Create a radial blur effect
 const blur = engine.block.createBlur('//ly.img.ubq/blur/radial');
 ```
 
@@ -183,6 +217,7 @@ CE.SDK provides four blur types:
 Each blur type has specific parameters to control its appearance. Configure them using `setFloat()`.
 
 ```typescript highlight-configure-blur
+// Configure radial blur parameters
 engine.block.setFloat(blur, 'blur/radial/blurRadius', 40);
 engine.block.setFloat(blur, 'blur/radial/radius', 100);
 engine.block.setFloat(blur, 'blur/radial/gradientRadius', 80);
@@ -221,11 +256,12 @@ engine.block.setFloat(blur, 'blur/radial/y', 0.5);
 After configuring the blur, apply it to the target block and enable it.
 
 ```typescript highlight-apply-blur
-engine.block.setBlur(imageBlock, blur);
-engine.block.setBlurEnabled(imageBlock, true);
+// Apply the blur to the image block
+engine.block.setBlur(sampleBlock, blur);
+engine.block.setBlurEnabled(sampleBlock, true);
 ```
 
-The blur takes effect immediately once enabled. You can modify parameters at any time and changes apply in real-time.
+The blur takes effect immediately once enabled. You can modify parameters at any time.
 
 ## Managing Blur
 
@@ -234,52 +270,115 @@ The blur takes effect immediately once enabled. You can modify parameters at any
 Retrieve the blur applied to a block using `getBlur()`. You can then read or modify its properties.
 
 ```typescript highlight-read-blur
-const appliedBlur = engine.block.getBlur(imageBlock);
-const isEnabled = engine.block.isBlurEnabled(imageBlock);
+// Access the applied blur and its properties
+const appliedBlur = engine.block.getBlur(sampleBlock);
+const isEnabled = engine.block.isBlurEnabled(sampleBlock);
 const blurType = engine.block.getType(appliedBlur);
 console.log('Blur type:', blurType, 'Enabled:', isEnabled);
 ```
 
 ### Enable/Disable Blur
 
-Toggle blur on and off without removing it using `setBlurEnabled()`. This preserves all blur parameters for quick before/after comparisons.
+Toggle blur on and off without removing it using `setBlurEnabled()`. This preserves all blur parameters for conditional processing.
 
 ```typescript highlight-toggle-blur
-engine.block.setBlurEnabled(imageBlock, false);
-const nowEnabled = engine.block.isBlurEnabled(imageBlock);
-console.log('Blur now enabled:', nowEnabled);
-engine.block.setBlurEnabled(imageBlock, true);
+  // Disable blur temporarily
+  engine.block.setBlurEnabled(sampleBlock, false);
+  console.log('Blur disabled:', !engine.block.isBlurEnabled(sampleBlock));
+
+  // Re-enable for final export
+  engine.block.setBlurEnabled(sampleBlock, true);
 ```
 
 When disabled, the blur remains attached to the block but doesn't render until re-enabled.
 
-### Share Blur Across Blocks
+## Blur Types
+
+### Uniform Blur
+
+Applies consistent softening across the entire element. Best for simple background blur or overall softening.
 
-A single blur instance can be applied to multiple blocks. Create the blur once, then assign it to each block with `setBlur()`.
+```typescript highlight-uniform-blur
+  // Create a uniform blur for even softening
+  const uniformBlock = await engine.block.addImage(imageUri, {
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, uniformBlock);
+  engine.block.setPositionX(uniformBlock, 350);
 
-```typescript
-const sharedBlur = engine.block.createBlur('//ly.img.ubq/blur/uniform');
-engine.block.setFloat(sharedBlur, 'blur/uniform/intensity', 0.4);
+  const uniformBlur = engine.block.createBlur('//ly.img.ubq/blur/uniform');
+  engine.block.setFloat(uniformBlur, 'blur/uniform/intensity', 0.6);
+  engine.block.setBlur(uniformBlock, uniformBlur);
+  engine.block.setBlurEnabled(uniformBlock, true);
+```
+
+### Linear Blur
+
+Creates a gradient blur effect along a line defined by two control points. Useful for directional focus effects.
+
+```typescript highlight-linear-blur
+  // Create a linear blur for gradient effect
+  const linearBlock = await engine.block.addImage(imageUri, {
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, linearBlock);
+  engine.block.setPositionY(linearBlock, 275);
+
+  const linearBlur = engine.block.createBlur('//ly.img.ubq/blur/linear');
+  engine.block.setFloat(linearBlur, 'blur/linear/blurRadius', 35);
+  engine.block.setFloat(linearBlur, 'blur/linear/x1', 0);
+  engine.block.setFloat(linearBlur, 'blur/linear/y1', 0);
+  engine.block.setFloat(linearBlur, 'blur/linear/x2', 1);
+  engine.block.setFloat(linearBlur, 'blur/linear/y2', 1);
+  engine.block.setBlur(linearBlock, linearBlur);
+  engine.block.setBlurEnabled(linearBlock, true);
+```
 
-engine.block.setBlur(block1, sharedBlur);
-engine.block.setBlur(block2, sharedBlur);
-engine.block.setBlurEnabled(block1, true);
-engine.block.setBlurEnabled(block2, true);
+### Mirrored Blur
+
+Creates a band of focus with blur on both sides, commonly known as a tilt-shift effect. The control points define the focus band orientation.
+
+```typescript highlight-mirrored-blur
+  // Create a mirrored blur for tilt-shift effect
+  const mirroredBlock = await engine.block.addImage(imageUri, {
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, mirroredBlock);
+  engine.block.setPositionX(mirroredBlock, 350);
+  engine.block.setPositionY(mirroredBlock, 275);
+
+  const mirroredBlur = engine.block.createBlur('//ly.img.ubq/blur/mirrored');
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/blurRadius', 30);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/gradientSize', 50);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/size', 75);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/x1', 0);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/y1', 0.3);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/x2', 1);
+  engine.block.setFloat(mirroredBlur, 'blur/mirrored/y2', 0.7);
+  engine.block.setBlur(mirroredBlock, mirroredBlur);
+  engine.block.setBlurEnabled(mirroredBlock, true);
 ```
 
-Changes to the shared blur affect all blocks using it.
+## Export Results
 
-### Replace Blur
+After applying blur effects, export the processed content to a file. CE.SDK supports various export formats including PNG, JPEG, and PDF.
 
-To change the blur type on a block, create a new blur and assign it with `setBlur()`. The previous blur association is automatically removed.
+```typescript highlight-export
+  // Export the scene to PNG
+  const blob = await engine.block.export(page, { mimeType: 'image/png' });
+  const buffer = Buffer.from(await blob.arrayBuffer());
 
-```typescript
-const newBlur = engine.block.createBlur('//ly.img.ubq/blur/linear');
-engine.block.setBlur(block, newBlur);
-engine.block.setBlurEnabled(block, true);
+  // Ensure output directory exists
+  if (!existsSync('output')) {
+    mkdirSync('output');
+  }
+
+  // Save to file
+  writeFileSync('output/blur-effects.png', buffer);
+  console.log('Exported to output/blur-effects.png');
 ```
 
-If the old blur isn't used elsewhere, destroy it with `engine.block.destroy(oldBlur)`.
+The export operation renders all blur effects and saves the result to the file system. Always dispose of the engine instance when processing is complete to free resources.
 
 ## Troubleshooting
 
@@ -372,11 +471,14 @@ This section describes the properties available for the **Uniform Type** (`//ly.
 | ------------------------ | ------- | ------- | ------------------- |
 | `blur/uniform/intensity` | `Float` | `0.5`   | The blur intensity. |
 
+
+
+
 ---
 
 ## 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