@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/filters-and-effects/create-custom-filters.md

@@ -1,54 +1,38 @@
-> 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) > [Create Custom Filters](./filters-and-effects/create-custom-filters.md)
 
 ---
 
-Extend CE.SDK with your own LUT filters by creating and registering custom filter asset sources for brand-specific color grading.
-
-![Create Custom Filters example showing images with custom filters applied](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Extend CE.SDK with your own LUT filters by creating and registering custom filter asset sources for server-side image processing pipelines.
 
 > **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-filters-and-effects-add-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-filters-and-effects-add-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-filters-and-effects-add-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-filters-and-effects-add-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-filters-and-effects-add-server-js)
 
-CE.SDK provides built-in LUT filters, but many applications need brand-specific color grading or custom filter collections. Custom filter asset sources let you register your own LUT filters that appear alongside or replace the defaults. Once registered, custom filters integrate seamlessly with the built-in UI and can be applied programmatically.
+CE.SDK provides built-in LUT filters, but many applications need brand-specific color grading or custom filter collections. Custom filter asset sources let you register your own LUT filters for automated batch processing and server-side image workflows. Once registered, custom filters can be queried and applied programmatically.
 
-```typescript file=@cesdk_web_examples/guides-filters-and-effects-add-browser/browser.ts reference-only
-import type {
-  AssetQueryData,
-  AssetResult,
+```typescript file=@cesdk_web_examples/guides-filters-and-effects-add-server-js/server-js.ts reference-only
+import CreativeEngine, {
   AssetSource,
+  AssetQueryData,
   AssetsQueryResult,
-  EditorPlugin,
-  EditorPluginContext
-} from '@cesdk/cesdk-js';
-import packageJson from './package.json';
-
-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';
+  AssetResult
+} from '@cesdk/node';
+import { config } from 'dotenv';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+
+// Load environment variables
+config();
 
 /**
- * CE.SDK Plugin: Create Custom Filters Guide
+ * CE.SDK Server Guide: Create Custom Filters
  *
  * Demonstrates creating and registering custom LUT filter asset sources:
  * - Creating a filter source with addSource()
@@ -56,63 +40,28 @@ import { DesignEditorConfig } from './design-editor/plugin';
  * - Loading filters from JSON configuration
  * - Querying custom filters
  * - Applying filters from custom sources
+ * - Exporting the result
  */
-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');
-    }
+// 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)
+});
 
-    await cesdk.addPlugin(new DesignEditorConfig());
+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];
 
-    // 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' }
-    });
-
-    const engine = cesdk.engine;
-    const page = engine.block.findByType('page')[0];
-
-    // Enable filters in the inspector panel using the Feature API
-    cesdk.feature.enable('ly.img.filter');
-
-    // Add a custom filter to the built-in LUT filter source
-    // The ID must follow the format //ly.img.cesdk.filters.lut/{name}
-    // for the UI to display the label correctly
-    engine.asset.addAssetToSource('ly.img.filter', {
-      id: '//ly.img.cesdk.filters.lut/mycustomfilter',
-      label: { en: 'MY CUSTOM FILTER' },
-      tags: { en: ['custom', 'brand'] },
+  // Define custom LUT filter assets with metadata
+  const customFilters: AssetResult[] = [
+    {
+      id: 'vintage-warm',
+      label: 'Vintage Warm',
+      tags: ['vintage', 'warm', 'retro'],
       meta: {
         uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
         thumbUri:
@@ -121,279 +70,100 @@ class Example implements EditorPlugin {
         verticalTileCount: '5',
         blockType: '//ly.img.ubq/effect/lut_filter'
       }
-    });
-
-    // Add translation for the custom filter label
-    cesdk.i18n.setTranslations({
-      en: {
-        'property.lutFilter.mycustomfilter': 'MY CUSTOM FILTER'
+    },
+    {
+      id: 'cool-cinema',
+      label: 'Cool Cinema',
+      tags: ['cinema', 'cool', 'film'],
+      meta: {
+        uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
+        thumbUri:
+          'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
+        horizontalTileCount: '5',
+        verticalTileCount: '5',
+        blockType: '//ly.img.ubq/effect/lut_filter'
       }
-    });
-
-    // Create a custom filter asset source for organizing multiple filters
-    const customFilterSource: AssetSource = {
-      id: 'my-custom-filters',
-
-      async findAssets(
-        queryData: AssetQueryData
-      ): Promise<AssetsQueryResult | undefined> {
-        // Define custom LUT filter assets
-        const filters: AssetResult[] = [
-          {
-            id: 'vintage-warm',
-            label: 'Vintage Warm',
-            tags: ['vintage', 'warm', 'retro'],
-            meta: {
-              uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-              thumbUri:
-                'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-              horizontalTileCount: '5',
-              verticalTileCount: '5',
-              blockType: '//ly.img.ubq/effect/lut_filter'
-            }
-          },
-          {
-            id: 'cool-cinema',
-            label: 'Cool Cinema',
-            tags: ['cinema', 'cool', 'film'],
-            meta: {
-              uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-              thumbUri:
-                'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-              horizontalTileCount: '5',
-              verticalTileCount: '5',
-              blockType: '//ly.img.ubq/effect/lut_filter'
-            }
-          },
-          {
-            id: 'bw-classic',
-            label: 'B&W Classic',
-            tags: ['black and white', 'classic', 'monochrome'],
-            meta: {
-              uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-              thumbUri:
-                'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-              horizontalTileCount: '5',
-              verticalTileCount: '5',
-              blockType: '//ly.img.ubq/effect/lut_filter'
-            }
-          }
-        ];
-
-        // Filter by query if provided
-        let filteredAssets = filters;
-        if (queryData.query) {
-          const searchTerm = queryData.query.toLowerCase();
-          filteredAssets = filters.filter(
-            (asset) =>
-              asset.label?.toLowerCase().includes(searchTerm) ||
-              asset.tags?.some((tag) => tag.toLowerCase().includes(searchTerm))
-          );
-        }
-
-        // Filter by groups if provided
-        if (queryData.groups && queryData.groups.length > 0) {
-          filteredAssets = filteredAssets.filter((asset) =>
-            asset.tags?.some((tag) => queryData.groups?.includes(tag))
-          );
-        }
-
-        // Handle pagination
-        const page = queryData.page ?? 0;
-        const perPage = queryData.perPage ?? 10;
-        const startIndex = page * perPage;
-        const paginatedAssets = filteredAssets.slice(
-          startIndex,
-          startIndex + perPage
-        );
-
-        return {
-          assets: paginatedAssets,
-          total: filteredAssets.length,
-          currentPage: page,
-          nextPage:
-            startIndex + perPage < filteredAssets.length ? page + 1 : undefined
-        };
-      },
-
-      // Return available filter categories
-      async getGroups(): Promise<string[]> {
-        return ['vintage', 'cinema', 'black and white'];
+    },
+    {
+      id: 'bw-classic',
+      label: 'B&W Classic',
+      tags: ['black and white', 'classic', 'monochrome'],
+      meta: {
+        uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
+        thumbUri:
+          'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
+        horizontalTileCount: '5',
+        verticalTileCount: '5',
+        blockType: '//ly.img.ubq/effect/lut_filter'
       }
-    };
-
-    // Register the custom filter source for programmatic access
-    engine.asset.addSource(customFilterSource);
-
-    // Load filters from a JSON configuration string
-    const filterConfigJSON = JSON.stringify({
-      version: '2.0.0',
-      id: 'my-json-filters',
-      assets: [
-        {
-          id: 'sunset-glow',
-          label: { en: 'Sunset Glow' },
-          tags: { en: ['warm', 'sunset', 'golden'] },
-          groups: ['Warm Tones'],
-          meta: {
-            uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-            thumbUri:
-              'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-            horizontalTileCount: '5',
-            verticalTileCount: '5',
-            blockType: '//ly.img.ubq/effect/lut_filter'
-          }
-        },
-        {
-          id: 'ocean-breeze',
-          label: { en: 'Ocean Breeze' },
-          tags: { en: ['cool', 'blue', 'ocean'] },
-          groups: ['Cool Tones'],
-          meta: {
-            uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-            thumbUri:
-              'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-            horizontalTileCount: '5',
-            verticalTileCount: '5',
-            blockType: '//ly.img.ubq/effect/lut_filter'
-          }
-        }
-      ]
-    });
-
-    // Create asset source from JSON string
-    const jsonSourceId =
-      await engine.asset.addLocalAssetSourceFromJSONString(filterConfigJSON);
-    // eslint-disable-next-line no-console
-    console.log('Created JSON-based filter source:', jsonSourceId);
-
-    // Query filters from our custom source for programmatic use
-    const customFilterResults = await engine.asset.findAssets(
-      'my-custom-filters',
-      {
-        page: 0,
-        perPage: 10
+    }
+  ];
+
+  // Create a custom filter asset source
+  const customFilterSource: AssetSource = {
+    id: 'my-custom-filters',
+
+    async findAssets(
+      queryData: AssetQueryData
+    ): Promise<AssetsQueryResult | undefined> {
+      // Filter by query if provided
+      let filteredAssets = customFilters;
+      if (queryData.query) {
+        const searchTerm = queryData.query.toLowerCase();
+        filteredAssets = customFilters.filter(
+          (asset) =>
+            asset.label?.toLowerCase().includes(searchTerm) ||
+            asset.tags?.some((tag) => tag.toLowerCase().includes(searchTerm))
+        );
       }
-    );
-
-    // Create an image block to demonstrate applying a custom filter
-    const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
-    const imageBlock = await engine.block.addImage(imageUri, {
-      x: 50,
-      y: 150,
-      size: { width: 300, height: 200 }
-    });
-    engine.block.appendChild(page, imageBlock);
-
-    // Get a filter from our custom source
-    const filterAsset = customFilterResults.assets[0];
-    if (filterAsset && filterAsset.meta) {
-      // Create and configure the LUT filter effect
-      const lutEffect = engine.block.createEffect(
-        '//ly.img.ubq/effect/lut_filter'
-      );
 
-      // Set LUT file URI from asset metadata
-      engine.block.setString(
-        lutEffect,
-        'effect/lut_filter/lutFileURI',
-        filterAsset.meta.uri as string
-      );
+      // Filter by groups if provided
+      if (queryData.groups && queryData.groups.length > 0) {
+        filteredAssets = filteredAssets.filter((asset) =>
+          asset.tags?.some((tag) => queryData.groups?.includes(tag))
+        );
+      }
 
-      // Configure LUT grid dimensions
-      engine.block.setInt(
-        lutEffect,
-        'effect/lut_filter/horizontalTileCount',
-        parseInt(filterAsset.meta.horizontalTileCount as string, 10)
-      );
-      engine.block.setInt(
-        lutEffect,
-        'effect/lut_filter/verticalTileCount',
-        parseInt(filterAsset.meta.verticalTileCount as string, 10)
+      // Handle pagination
+      const currentPage = queryData.page ?? 0;
+      const perPage = queryData.perPage ?? 10;
+      const startIndex = currentPage * perPage;
+      const paginatedAssets = filteredAssets.slice(
+        startIndex,
+        startIndex + perPage
       );
 
-      // Set filter intensity (0.0 to 1.0)
-      engine.block.setFloat(lutEffect, 'effect/lut_filter/intensity', 0.85);
+      return {
+        assets: paginatedAssets,
+        total: filteredAssets.length,
+        currentPage,
+        nextPage:
+          startIndex + perPage < filteredAssets.length
+            ? currentPage + 1
+            : undefined
+      };
+    },
 
-      // Apply the effect to the image block
-      engine.block.appendEffect(imageBlock, lutEffect);
+    // Return available filter categories
+    async getGroups(): Promise<string[]> {
+      return ['vintage', 'cinema', 'black and white'];
     }
+  };
 
-    // Create a second image without a filter for comparison
-    const imageBlock2 = await engine.block.addImage(imageUri, {
-      x: 450,
-      y: 150,
-      size: { width: 300, height: 200 }
-    });
-    engine.block.appendChild(page, imageBlock2);
-
-    // Select the filtered image to show the filter in the inspector
-    engine.block.select(imageBlock);
-
-    // eslint-disable-next-line no-console
-    console.log(
-      'Custom filters guide initialized. Select an image to see filters in the inspector panel.'
-    );
-  }
-}
+  // Register the custom filter source
+  engine.asset.addSource(customFilterSource);
+  console.log('Registered custom filter source: my-custom-filters');
 
-export default Example;
-```
-
-This guide covers how to create filter asset sources, define filter metadata, load filters from JSON configuration, and apply custom filters to design elements.
-
-## Filter Asset Metadata
-
-LUT filters need these properties in the `meta` object:
-
-- **`uri`** - URL to the LUT image file (PNG format)
-- **`thumbUri`** - URL to the thumbnail preview image
-- **`horizontalTileCount`** - Number of horizontal tiles in the LUT grid (typically 5 or 8)
-- **`verticalTileCount`** - Number of vertical tiles in the LUT grid (typically 5 or 8)
-- **`blockType`** - Must be `//ly.img.ubq/effect/lut_filter` for LUT filters
-
-## Adding a Custom Filter
-
-We register a custom filter source using `engine.asset.addSource()` with a `findAssets` callback. This callback returns filter assets matching the query parameters. After registering the source, we use `cesdk.ui.updateAssetLibraryEntry()` to add our custom source to the filter inspector panel.
-
-```typescript highlight-create-custom-source
-// Add a custom filter to the built-in LUT filter source
-// The ID must follow the format //ly.img.cesdk.filters.lut/{name}
-// for the UI to display the label correctly
-engine.asset.addAssetToSource('ly.img.filter', {
-  id: '//ly.img.cesdk.filters.lut/mycustomfilter',
-  label: { en: 'MY CUSTOM FILTER' },
-  tags: { en: ['custom', 'brand'] },
-  meta: {
-    uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-    thumbUri:
-      'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-    horizontalTileCount: '5',
-    verticalTileCount: '5',
-    blockType: '//ly.img.ubq/effect/lut_filter'
-  }
-});
-
-// Add translation for the custom filter label
-cesdk.i18n.setTranslations({
-  en: {
-    'property.lutFilter.mycustomfilter': 'MY CUSTOM FILTER'
-  }
-});
-
-// Create a custom filter asset source for organizing multiple filters
-const customFilterSource: AssetSource = {
-  id: 'my-custom-filters',
-
-  async findAssets(
-    queryData: AssetQueryData
-  ): Promise<AssetsQueryResult | undefined> {
-    // Define custom LUT filter assets
-    const filters: AssetResult[] = [
+  // Load filters from a JSON configuration string
+  const filterConfigJSON = JSON.stringify({
+    version: '2.0.0',
+    id: 'my-json-filters',
+    assets: [
       {
-        id: 'vintage-warm',
-        label: 'Vintage Warm',
-        tags: ['vintage', 'warm', 'retro'],
+        id: 'sunset-glow',
+        label: { en: 'Sunset Glow' },
+        tags: { en: ['warm', 'sunset', 'golden'] },
+        groups: ['Warm Tones'],
         meta: {
           uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
           thumbUri:
@@ -404,109 +174,168 @@ const customFilterSource: AssetSource = {
         }
       },
       {
-        id: 'cool-cinema',
-        label: 'Cool Cinema',
-        tags: ['cinema', 'cool', 'film'],
+        id: 'ocean-breeze',
+        label: { en: 'Ocean Breeze' },
+        tags: { en: ['cool', 'blue', 'ocean'] },
+        groups: ['Cool Tones'],
         meta: {
-          uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
+          uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
           thumbUri:
-            'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-          horizontalTileCount: '5',
-          verticalTileCount: '5',
-          blockType: '//ly.img.ubq/effect/lut_filter'
-        }
-      },
-      {
-        id: 'bw-classic',
-        label: 'B&W Classic',
-        tags: ['black and white', 'classic', 'monochrome'],
-        meta: {
-          uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
-          thumbUri:
-            'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
+            'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
           horizontalTileCount: '5',
           verticalTileCount: '5',
           blockType: '//ly.img.ubq/effect/lut_filter'
         }
       }
-    ];
-
-    // Filter by query if provided
-    let filteredAssets = filters;
-    if (queryData.query) {
-      const searchTerm = queryData.query.toLowerCase();
-      filteredAssets = filters.filter(
-        (asset) =>
-          asset.label?.toLowerCase().includes(searchTerm) ||
-          asset.tags?.some((tag) => tag.toLowerCase().includes(searchTerm))
-      );
-    }
+    ]
+  });
 
-    // Filter by groups if provided
-    if (queryData.groups && queryData.groups.length > 0) {
-      filteredAssets = filteredAssets.filter((asset) =>
-        asset.tags?.some((tag) => queryData.groups?.includes(tag))
-      );
+  // Create asset source from JSON string
+  const jsonSourceId =
+    await engine.asset.addLocalAssetSourceFromJSONString(filterConfigJSON);
+  console.log('Created JSON-based filter source:', jsonSourceId);
+
+  // Query filters from the custom source
+  const customFilterResults = await engine.asset.findAssets(
+    'my-custom-filters',
+    {
+      page: 0,
+      perPage: 10
     }
+  );
+  console.log('Found', customFilterResults.total, 'filters in custom source');
+
+  // Query filters from the JSON source
+  const jsonFilterResults = await engine.asset.findAssets('my-json-filters', {
+    page: 0,
+    perPage: 10
+  });
+  console.log('Found', jsonFilterResults.total, 'filters in JSON source');
+
+  // List all registered asset sources
+  const allSources = engine.asset.findAllSources();
+  console.log('Registered sources:', allSources);
+
+  // Create an image block
+  const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
+  const imageBlock = await engine.block.addImage(imageUri, {
+    x: 50,
+    y: 50,
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, imageBlock);
+
+  // Get the first filter from our custom source
+  const filterAsset = customFilterResults.assets[0];
+  if (filterAsset && filterAsset.meta) {
+    // Create and configure the LUT filter effect
+    const lutEffect = engine.block.createEffect(
+      '//ly.img.ubq/effect/lut_filter'
+    );
 
-    // Handle pagination
-    const page = queryData.page ?? 0;
-    const perPage = queryData.perPage ?? 10;
-    const startIndex = page * perPage;
-    const paginatedAssets = filteredAssets.slice(
-      startIndex,
-      startIndex + perPage
+    // Set LUT file URI from asset metadata
+    engine.block.setString(
+      lutEffect,
+      'effect/lut_filter/lutFileURI',
+      filterAsset.meta.uri as string
     );
 
-    return {
-      assets: paginatedAssets,
-      total: filteredAssets.length,
-      currentPage: page,
-      nextPage:
-        startIndex + perPage < filteredAssets.length ? page + 1 : undefined
-    };
-  },
-
-  // Return available filter categories
-  async getGroups(): Promise<string[]> {
-    return ['vintage', 'cinema', 'black and white'];
+    // Configure LUT grid dimensions
+    engine.block.setInt(
+      lutEffect,
+      'effect/lut_filter/horizontalTileCount',
+      parseInt(filterAsset.meta.horizontalTileCount as string, 10)
+    );
+    engine.block.setInt(
+      lutEffect,
+      'effect/lut_filter/verticalTileCount',
+      parseInt(filterAsset.meta.verticalTileCount as string, 10)
+    );
+
+    // Set filter intensity (0.0 to 1.0)
+    engine.block.setFloat(lutEffect, 'effect/lut_filter/intensity', 0.85);
+
+    // Apply the effect to the image block
+    engine.block.appendEffect(imageBlock, lutEffect);
+    console.log('Applied filter:', filterAsset.label);
   }
-};
 
-// Register the custom filter source for programmatic access
-engine.asset.addSource(customFilterSource);
-```
+  // Create a second image block with a filter from JSON source
+  const imageBlock2 = await engine.block.addImage(imageUri, {
+    x: 450,
+    y: 50,
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, imageBlock2);
+
+  // Get a filter from the JSON source
+  const jsonFilterAsset = jsonFilterResults.assets[0];
+  if (jsonFilterAsset && jsonFilterAsset.meta) {
+    const lutEffect2 = engine.block.createEffect(
+      '//ly.img.ubq/effect/lut_filter'
+    );
 
-The `findAssets` callback receives query parameters including pagination (`page`, `perPage`), search terms (`query`), and category filters (`groups`). We filter and paginate the results accordingly.
+    engine.block.setString(
+      lutEffect2,
+      'effect/lut_filter/lutFileURI',
+      jsonFilterAsset.meta.uri as string
+    );
+    engine.block.setInt(
+      lutEffect2,
+      'effect/lut_filter/horizontalTileCount',
+      parseInt(jsonFilterAsset.meta.horizontalTileCount as string, 10)
+    );
+    engine.block.setInt(
+      lutEffect2,
+      'effect/lut_filter/verticalTileCount',
+      parseInt(jsonFilterAsset.meta.verticalTileCount as string, 10)
+    );
+    engine.block.setFloat(lutEffect2, 'effect/lut_filter/intensity', 0.85);
 
-The `updateAssetLibraryEntry()` call connects our custom source to the `ly.img.filter` panel, making our filters appear alongside the built-in LUT filters when a user selects an image.
+    engine.block.appendEffect(imageBlock2, lutEffect2);
+    console.log('Applied JSON filter:', jsonFilterAsset.label);
+  }
 
-### Filter Asset Structure
+  // Export the scene to PNG
+  const blob = await engine.block.export(page, { mimeType: 'image/png' });
+  const buffer = Buffer.from(await blob.arrayBuffer());
 
-Each filter asset returned by `findAssets` needs:
+  // Ensure output directory exists
+  if (!existsSync('output')) {
+    mkdirSync('output');
+  }
 
-- **`id`** - Unique identifier for the filter
-- **`label`** - Display name shown in the UI
-- **`tags`** - Keywords for search filtering
-- **`meta`** - Object containing LUT configuration (uri, thumbUri, tile counts, blockType)
+  // Save to file
+  writeFileSync('output/custom-filters.png', buffer);
+  console.log('Exported to output/custom-filters.png');
+} finally {
+  engine.dispose();
+}
+```
 
-The optional `getGroups()` method returns available filter categories for the UI.
+This guide covers how to create filter asset sources, define filter metadata, load filters from JSON configuration, query custom sources, and apply filters to images.
 
-## Loading Filters from JSON Configuration
+## Filter Asset Metadata
 
-For larger filter collections, we load definitions from JSON using `engine.asset.addLocalAssetSourceFromJSONString()`. This approach simplifies management of filter libraries.
+LUT filters need these properties in the `meta` object:
 
-```typescript highlight-load-from-json-string
-// Load filters from a JSON configuration string
-const filterConfigJSON = JSON.stringify({
-  version: '2.0.0',
-  id: 'my-json-filters',
-  assets: [
+- **`uri`** - URL to the LUT image file (PNG format)
+- **`thumbUri`** - URL to the thumbnail preview image
+- **`horizontalTileCount`** - Number of horizontal tiles in the LUT grid (typically 5 or 8)
+- **`verticalTileCount`** - Number of vertical tiles in the LUT grid (typically 5 or 8)
+- **`blockType`** - Must be `//ly.img.ubq/effect/lut_filter` for LUT filters
+
+## Adding a Custom Filter
+
+We register a custom filter source using `engine.asset.addSource()` with a `findAssets` callback. This callback returns filter assets matching the query parameters including pagination, search terms, and category filters.
+
+```typescript highlight-create-custom-source
+  // Define custom LUT filter assets with metadata
+  const customFilters: AssetResult[] = [
     {
-      id: 'sunset-glow',
-      label: { en: 'Sunset Glow' },
-      tags: { en: ['warm', 'sunset', 'golden'] },
-      groups: ['Warm Tones'],
+      id: 'vintage-warm',
+      label: 'Vintage Warm',
+      tags: ['vintage', 'warm', 'retro'],
       meta: {
         uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
         thumbUri:
@@ -517,27 +346,147 @@ const filterConfigJSON = JSON.stringify({
       }
     },
     {
-      id: 'ocean-breeze',
-      label: { en: 'Ocean Breeze' },
-      tags: { en: ['cool', 'blue', 'ocean'] },
-      groups: ['Cool Tones'],
+      id: 'cool-cinema',
+      label: 'Cool Cinema',
+      tags: ['cinema', 'cool', 'film'],
       meta: {
-        uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
+        uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
         thumbUri:
-          'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
+          'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
+        horizontalTileCount: '5',
+        verticalTileCount: '5',
+        blockType: '//ly.img.ubq/effect/lut_filter'
+      }
+    },
+    {
+      id: 'bw-classic',
+      label: 'B&W Classic',
+      tags: ['black and white', 'classic', 'monochrome'],
+      meta: {
+        uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
+        thumbUri:
+          'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
         horizontalTileCount: '5',
         verticalTileCount: '5',
         blockType: '//ly.img.ubq/effect/lut_filter'
       }
     }
-  ]
-});
+  ];
+
+  // Create a custom filter asset source
+  const customFilterSource: AssetSource = {
+    id: 'my-custom-filters',
+
+    async findAssets(
+      queryData: AssetQueryData
+    ): Promise<AssetsQueryResult | undefined> {
+      // Filter by query if provided
+      let filteredAssets = customFilters;
+      if (queryData.query) {
+        const searchTerm = queryData.query.toLowerCase();
+        filteredAssets = customFilters.filter(
+          (asset) =>
+            asset.label?.toLowerCase().includes(searchTerm) ||
+            asset.tags?.some((tag) => tag.toLowerCase().includes(searchTerm))
+        );
+      }
+
+      // Filter by groups if provided
+      if (queryData.groups && queryData.groups.length > 0) {
+        filteredAssets = filteredAssets.filter((asset) =>
+          asset.tags?.some((tag) => queryData.groups?.includes(tag))
+        );
+      }
+
+      // Handle pagination
+      const currentPage = queryData.page ?? 0;
+      const perPage = queryData.perPage ?? 10;
+      const startIndex = currentPage * perPage;
+      const paginatedAssets = filteredAssets.slice(
+        startIndex,
+        startIndex + perPage
+      );
+
+      return {
+        assets: paginatedAssets,
+        total: filteredAssets.length,
+        currentPage,
+        nextPage:
+          startIndex + perPage < filteredAssets.length
+            ? currentPage + 1
+            : undefined
+      };
+    },
+
+    // Return available filter categories
+    async getGroups(): Promise<string[]> {
+      return ['vintage', 'cinema', 'black and white'];
+    }
+  };
+
+  // Register the custom filter source
+  engine.asset.addSource(customFilterSource);
+  console.log('Registered custom filter source: my-custom-filters');
+```
+
+The `findAssets` callback receives query parameters including pagination (`page`, `perPage`), search terms (`query`), and category filters (`groups`). We filter and paginate the results accordingly.
+
+### Filter Asset Structure
+
+Each filter asset returned by `findAssets` needs:
+
+- **`id`** - Unique identifier for the filter
+- **`label`** - Display name for the filter
+- **`tags`** - Keywords for search filtering
+- **`meta`** - Object containing LUT configuration (uri, thumbUri, tile counts, blockType)
+
+The optional `getGroups()` method returns available filter categories for organizing filters.
+
+## Loading Filters from JSON Configuration
+
+For larger filter collections, we load definitions from JSON using `engine.asset.addLocalAssetSourceFromJSONString()`. This approach simplifies management of filter libraries.
+
+```typescript highlight-load-from-json-string
+  // Load filters from a JSON configuration string
+  const filterConfigJSON = JSON.stringify({
+    version: '2.0.0',
+    id: 'my-json-filters',
+    assets: [
+      {
+        id: 'sunset-glow',
+        label: { en: 'Sunset Glow' },
+        tags: { en: ['warm', 'sunset', 'golden'] },
+        groups: ['Warm Tones'],
+        meta: {
+          uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
+          thumbUri:
+            'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_ad1920_5_5_128.png',
+          horizontalTileCount: '5',
+          verticalTileCount: '5',
+          blockType: '//ly.img.ubq/effect/lut_filter'
+        }
+      },
+      {
+        id: 'ocean-breeze',
+        label: { en: 'Ocean Breeze' },
+        tags: { en: ['cool', 'blue', 'ocean'] },
+        groups: ['Cool Tones'],
+        meta: {
+          uri: 'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
+          thumbUri:
+            'https://cdn.img.ly/assets/v4/ly.img.filter.lut/LUTs/imgly_lut_bw_5_5_128.png',
+          horizontalTileCount: '5',
+          verticalTileCount: '5',
+          blockType: '//ly.img.ubq/effect/lut_filter'
+        }
+      }
+    ]
+  });
 
-// Create asset source from JSON string
-const jsonSourceId =
-  await engine.asset.addLocalAssetSourceFromJSONString(filterConfigJSON);
-// eslint-disable-next-line no-console
-console.log('Created JSON-based filter source:', jsonSourceId);
+  // Create asset source from JSON string
+  const jsonSourceId =
+    await engine.asset.addLocalAssetSourceFromJSONString(filterConfigJSON);
+  console.log('Created JSON-based filter source:', jsonSourceId);
 ```
 
 ### JSON Structure for Filter Assets
@@ -553,48 +502,179 @@ Each asset in the array contains:
 - **`id`** - Unique filter identifier
 - **`label`** - Localized label object (e.g., `{ "en": "Filter Name" }`)
 - **`tags`** - Localized tags for search
-- **`groups`** - Category assignments for UI organization
+- **`groups`** - Category assignments for organization
 - **`meta`** - LUT configuration properties
 
 For filters hosted on a CDN, use `engine.asset.addLocalAssetSourceFromJSONURI()` instead, which resolves relative URLs against the JSON file's parent directory.
 
+## Querying and Applying Filters
+
+We query filters from registered sources using `engine.asset.findAssets()`, then create and configure LUT filter effects from the returned metadata.
+
+```typescript highlight-query-custom-filters
+  // Query filters from the custom source
+  const customFilterResults = await engine.asset.findAssets(
+    'my-custom-filters',
+    {
+      page: 0,
+      perPage: 10
+    }
+  );
+  console.log('Found', customFilterResults.total, 'filters in custom source');
+
+  // Query filters from the JSON source
+  const jsonFilterResults = await engine.asset.findAssets('my-json-filters', {
+    page: 0,
+    perPage: 10
+  });
+  console.log('Found', jsonFilterResults.total, 'filters in JSON source');
+
+  // List all registered asset sources
+  const allSources = engine.asset.findAllSources();
+  console.log('Registered sources:', allSources);
+```
+
+We create a `lut_filter` effect using `engine.block.createEffect()` and configure it with metadata from the queried filter asset. The effect is then attached to an image block.
+
+```typescript highlight-apply-custom-filter
+  // Create an image block
+  const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
+  const imageBlock = await engine.block.addImage(imageUri, {
+    x: 50,
+    y: 50,
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, imageBlock);
+
+  // Get the first filter from our custom source
+  const filterAsset = customFilterResults.assets[0];
+  if (filterAsset && filterAsset.meta) {
+    // Create and configure the LUT filter effect
+    const lutEffect = engine.block.createEffect(
+      '//ly.img.ubq/effect/lut_filter'
+    );
+
+    // Set LUT file URI from asset metadata
+    engine.block.setString(
+      lutEffect,
+      'effect/lut_filter/lutFileURI',
+      filterAsset.meta.uri as string
+    );
+
+    // Configure LUT grid dimensions
+    engine.block.setInt(
+      lutEffect,
+      'effect/lut_filter/horizontalTileCount',
+      parseInt(filterAsset.meta.horizontalTileCount as string, 10)
+    );
+    engine.block.setInt(
+      lutEffect,
+      'effect/lut_filter/verticalTileCount',
+      parseInt(filterAsset.meta.verticalTileCount as string, 10)
+    );
+
+    // Set filter intensity (0.0 to 1.0)
+    engine.block.setFloat(lutEffect, 'effect/lut_filter/intensity', 0.85);
+
+    // Apply the effect to the image block
+    engine.block.appendEffect(imageBlock, lutEffect);
+    console.log('Applied filter:', filterAsset.label);
+  }
+```
+
+We can apply filters from any registered source, including JSON-based sources.
+
+```typescript highlight-apply-json-filter
+  // Create a second image block with a filter from JSON source
+  const imageBlock2 = await engine.block.addImage(imageUri, {
+    x: 450,
+    y: 50,
+    size: { width: 300, height: 225 }
+  });
+  engine.block.appendChild(page, imageBlock2);
+
+  // Get a filter from the JSON source
+  const jsonFilterAsset = jsonFilterResults.assets[0];
+  if (jsonFilterAsset && jsonFilterAsset.meta) {
+    const lutEffect2 = engine.block.createEffect(
+      '//ly.img.ubq/effect/lut_filter'
+    );
+
+    engine.block.setString(
+      lutEffect2,
+      'effect/lut_filter/lutFileURI',
+      jsonFilterAsset.meta.uri as string
+    );
+    engine.block.setInt(
+      lutEffect2,
+      'effect/lut_filter/horizontalTileCount',
+      parseInt(jsonFilterAsset.meta.horizontalTileCount as string, 10)
+    );
+    engine.block.setInt(
+      lutEffect2,
+      'effect/lut_filter/verticalTileCount',
+      parseInt(jsonFilterAsset.meta.verticalTileCount as string, 10)
+    );
+    engine.block.setFloat(lutEffect2, 'effect/lut_filter/intensity', 0.85);
+
+    engine.block.appendEffect(imageBlock2, lutEffect2);
+    console.log('Applied JSON filter:', jsonFilterAsset.label);
+  }
+```
+
+After applying filters, we export the scene to PNG.
+
+```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());
+
+  // Ensure output directory exists
+  if (!existsSync('output')) {
+    mkdirSync('output');
+  }
+
+  // Save to file
+  writeFileSync('output/custom-filters.png', buffer);
+  console.log('Exported to output/custom-filters.png');
+```
+
 ## Troubleshooting
 
-### Filters Not Appearing in UI
+### Filters Not Found in Query
 
-- Verify the asset source is registered before loading the scene
+- Verify the asset source is registered with `engine.asset.addSource()` or `addLocalAssetSourceFromJSONString()`
 - Check that filter metadata includes all required fields (`uri`, `thumbUri`, tile counts)
 - Ensure the `blockType` is set to `//ly.img.ubq/effect/lut_filter`
-- Confirm thumbnails are accessible URLs
+- Confirm the source ID matches when calling `findAssets()`
 
 ### LUT Not Rendering Correctly
 
 - Verify tile count values match the actual LUT image grid dimensions
-- Check that the LUT image URL is CORS-enabled for cross-origin requests
+- Check that the LUT image URL is accessible from your server
 - Confirm the LUT image uses PNG format
 
-### Filter Thumbnails Missing
+### JSON Source Not Loading
 
-- Verify `thumbUri` points to an accessible image
-- Check that thumbnail URLs don't have CORS restrictions
-- Ensure thumbnail dimensions are appropriate for UI display (typically 100-200px)
+- Verify JSON structure matches the required format with `version`, `id`, and `assets`
+- Ensure asset metadata includes required fields
+- Check for JSON syntax errors
 
 ## API Reference
 
-| Method                                                           | Description                                                                   |
-| ---------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `engine.asset.addSource(source)`                                 | Register a custom asset source with findAssets callback                       |
-| `engine.asset.addLocalAssetSourceFromJSONString(json, basePath)` | Create asset source from inline JSON configuration                            |
-| `engine.asset.addLocalAssetSourceFromJSONURI(uri)`               | Load asset source from remote JSON file                                       |
-| `engine.asset.findAssets(sourceId, query)`                       | Query assets from a registered source                                         |
-| `engine.asset.findAllSources()`                                  | Get all registered asset source IDs                                           |
-| `engine.asset.removeSource(id)`                                  | Remove a registered asset source                                              |
-| `cesdk.ui.updateAssetLibraryEntry(entryId, config)`              | Add custom sources to filter inspector panel                                  |
-| `engine.block.createEffect(type)`                                | Create effect instance (use `//ly.img.ubq/effect/lut_filter` for LUT filters) |
-| `engine.block.setString(effect, property, value)`                | Set string property (LUT file URI)                                            |
-| `engine.block.setInt(effect, property, value)`                   | Set integer property (tile counts)                                            |
-| `engine.block.setFloat(effect, property, value)`                 | Set float property (intensity)                                                |
-| `engine.block.appendEffect(block, effect)`                       | Add effect to block's effect stack                                            |
+| Method | Description |
+| --- | --- |
+| `engine.asset.addSource(source)` | Register a custom asset source with findAssets callback |
+| `engine.asset.addLocalAssetSourceFromJSONString(json, basePath)` | Create asset source from inline JSON configuration |
+| `engine.asset.addLocalAssetSourceFromJSONURI(uri)` | Load asset source from remote JSON file |
+| `engine.asset.findAssets(sourceId, query)` | Query assets from a registered source |
+| `engine.asset.findAllSources()` | Get all registered asset source IDs |
+| `engine.asset.removeSource(id)` | Remove a registered asset source |
+| `engine.block.createEffect(type)` | Create effect instance (use `//ly.img.ubq/effect/lut_filter` for LUT filters) |
+| `engine.block.setString(effect, property, value)` | Set string property (LUT file URI) |
+| `engine.block.setInt(effect, property, value)` | Set integer property (tile counts) |
+| `engine.block.setFloat(effect, property, value)` | Set float property (intensity) |
+| `engine.block.appendEffect(block, effect)` | Add effect to block's effect stack |
 
 ## Next Steps
 
@@ -604,11 +684,13 @@ Now that you understand how to create and register custom filter sources, explor
 - [Create a Custom LUT Filter](./filters-and-effects/create-custom-lut-filter.md) - Understand LUT image format and create your own color grading filters
 - [Blur Effects](./filters-and-effects/blur.md) - Add blur effects to images and videos
 
+
+
 ---
 
 ## 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