@imgly/codesign-mcp 0.1.5 → 0.1.7

package/assets/docs/guide/edit-video/transform/rotate.md

@@ -1,241 +1,232 @@
-> 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) > [Create and Edit Videos](./create-video.md) > [Transform](./edit-video/transform.md) > [Rotate](./edit-video/transform/rotate.md)
 
 ---
 
-Rotate video elements to any angle using radians or degrees, with precise programmatic control and UI rotation handles.
-
-![Rotate videos example showing videos at different rotation angles](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Rotate video elements to any angle using radians or degrees, with precise programmatic control in headless Node.js environments.
 
 > **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-create-video-transform-rotate-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-video-transform-rotate-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-create-video-transform-rotate-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-create-video-transform-rotate-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-video-transform-rotate-server-js)
 
 Rotation in CE.SDK occurs around the block's center point. All rotation values use radians, where `Math.PI` equals 180 degrees. Positive values rotate counterclockwise, negative values rotate clockwise.
 
-```typescript file=@cesdk_web_examples/guides-create-video-transform-rotate-browser/browser.ts reference-only
-import CreativeEditorSDK, {
-  type EditorPlugin,
-  type EditorPluginContext
-} from '@cesdk/cesdk-js';
-
-import {
-  BlurAssetSource,
-  CaptionPresetsAssetSource,
-  ColorPaletteAssetSource,
-  CropPresetsAssetSource,
-  DemoAssetSources,
-  EffectsAssetSource,
-  FiltersAssetSource,
-  PagePresetsAssetSource,
-  StickerAssetSource,
-  TextAssetSource,
-  TextComponentAssetSource,
-  TypefaceAssetSource,
-  UploadAssetSources,
-  VectorShapeAssetSource
-} from '@cesdk/cesdk-js/plugins';
-import { VideoEditorConfig } from './video-editor/plugin';
-
-class Example implements EditorPlugin {
-  name = 'guides-create-video-transform-rotate-browser';
-
-  version = CreativeEditorSDK.version;
-
-  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
-    if (!cesdk) {
-      throw new Error('CE.SDK instance is required for this plugin');
-    }
-
-    await cesdk.addPlugin(new VideoEditorConfig());
-
-    // Add 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 UploadAssetSources({
-        include: [
-          'ly.img.image.upload',
-          'ly.img.video.upload',
-          'ly.img.audio.upload'
-        ]
-      })
-    );
-    await cesdk.addPlugin(
-      new DemoAssetSources({
-        include: [
-          'ly.img.templates.video.*',
-          'ly.img.image.*',
-          'ly.img.audio.*',
-          'ly.img.video.*'
-        ]
-      })
-    );
-    await cesdk.addPlugin(new EffectsAssetSource());
-    await cesdk.addPlugin(new FiltersAssetSource());
-    await cesdk.addPlugin(
-      new PagePresetsAssetSource({
-        include: [
-          'ly.img.page.presets.instagram.*',
-          'ly.img.page.presets.facebook.*',
-          'ly.img.page.presets.x.*',
-          'ly.img.page.presets.linkedin.*',
-          'ly.img.page.presets.pinterest.*',
-          'ly.img.page.presets.tiktok.*',
-          'ly.img.page.presets.youtube.*',
-          'ly.img.page.presets.video.*'
-        ]
-      })
-    );
-    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', {
-      layout: 'DepthStack',
-      page: { width: 800, height: 500, unit: 'Pixel' }
-    });
-
-    const engine = cesdk.engine;
-    const pages = engine.block.findByType('page');
-    const page = pages.length > 0 ? pages[0] : engine.scene.get();
-
-    // Enable fill and set page fill color to #6686FF
-    engine.block.setFillEnabled(page, true);
-    engine.block.setColor(engine.block.getFill(page), 'fill/color/value', {
-      r: 102 / 255,
-      g: 134 / 255,
-      b: 255 / 255,
-      a: 1
-    });
-
-    // Demo 1: Rotated Video - Rotated 45 degrees
-    const rotatedVideo = await engine.block.addVideo(
-      'https://img.ly/static/ubq_video_samples/bbb.mp4',
-      200,
-      150
-    );
-    engine.block.appendChild(page, rotatedVideo);
-    engine.block.setPositionX(rotatedVideo, 50);
-    engine.block.setPositionY(rotatedVideo, 100);
-
-    // Rotate the video 45 degrees (in radians)
-    const toRadians = (degrees: number) => (degrees * Math.PI) / 180;
-    engine.block.setRotation(rotatedVideo, toRadians(45));
-
-    // Add label for rotated video
-    const text1 = engine.block.create('text');
-    engine.block.setString(text1, 'text/text', '45° Rotation');
-    engine.block.setFloat(text1, 'text/fontSize', 28);
-    engine.block.setEnum(text1, 'text/horizontalAlignment', 'Center');
-    engine.block.setWidth(text1, 200);
-    engine.block.setPositionX(text1, 50);
-    engine.block.setPositionY(text1, 320);
-    engine.block.setFillEnabled(text1, true);
-    engine.block.setColor(engine.block.getFill(text1), 'fill/color/value', {
-      r: 1,
-      g: 1,
-      b: 1,
-      a: 1
-    });
-    engine.block.appendChild(page, text1);
-
-    // Get current rotation value
-    const currentRotation = engine.block.getRotation(rotatedVideo);
-    const toDegrees = (radians: number) => (radians * 180) / Math.PI;
-    console.log('Current rotation:', toDegrees(currentRotation), 'degrees');
-
-    // Demo 2: 90 Degree Rotation
-    const rotatedVideo90 = await engine.block.addVideo(
-      'https://img.ly/static/ubq_video_samples/bbb.mp4',
-      200,
-      150
-    );
-    engine.block.appendChild(page, rotatedVideo90);
-    engine.block.setPositionX(rotatedVideo90, 300);
-    engine.block.setPositionY(rotatedVideo90, 100);
-
-    // Rotate 90 degrees using Math.PI / 2
-    engine.block.setRotation(rotatedVideo90, Math.PI / 2);
-
-    // Add label for 90 degree rotation
-    const text2 = engine.block.create('text');
-    engine.block.setString(text2, 'text/text', '90° Rotation');
-    engine.block.setFloat(text2, 'text/fontSize', 28);
-    engine.block.setEnum(text2, 'text/horizontalAlignment', 'Center');
-    engine.block.setWidth(text2, 200);
-    engine.block.setPositionX(text2, 300);
-    engine.block.setPositionY(text2, 320);
-    engine.block.setFillEnabled(text2, true);
-    engine.block.setColor(engine.block.getFill(text2), 'fill/color/value', {
-      r: 1,
-      g: 1,
-      b: 1,
-      a: 1
-    });
-    engine.block.appendChild(page, text2);
-
-    // Demo 3: Locked Rotation - Rotation is disabled for this block
-    const lockedVideo = await engine.block.addVideo(
-      'https://img.ly/static/ubq_video_samples/bbb.mp4',
-      200,
-      150
-    );
-    engine.block.appendChild(page, lockedVideo);
-    engine.block.setPositionX(lockedVideo, 550);
-    engine.block.setPositionY(lockedVideo, 150);
-
-    // Disable rotation for this specific block
-    engine.block.setScopeEnabled(lockedVideo, 'layer/rotate', false);
-
-    // Add label for locked video
-    const text3 = engine.block.create('text');
-    engine.block.setString(text3, 'text/text', 'Rotation Locked');
-    engine.block.setFloat(text3, 'text/fontSize', 28);
-    engine.block.setEnum(text3, 'text/horizontalAlignment', 'Center');
-    engine.block.setWidth(text3, 200);
-    engine.block.setPositionX(text3, 550);
-    engine.block.setPositionY(text3, 320);
-    engine.block.setFillEnabled(text3, true);
-    engine.block.setColor(engine.block.getFill(text3), 'fill/color/value', {
-      r: 1,
-      g: 1,
-      b: 1,
-      a: 1
-    });
-    engine.block.appendChild(page, text3);
-
-    // Check if rotation is enabled for a block
-    const canRotate = engine.block.isScopeEnabled(lockedVideo, 'layer/rotate');
-    console.log('Rotation enabled:', canRotate);
-
-    // Set playhead position to 2 seconds
-    engine.block.setPlaybackTime(page, 2);
+```typescript file=@cesdk_web_examples/guides-create-video-transform-rotate-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { config } from 'dotenv';
+
+// Load environment variables
+config();
+
+/**
+ * CE.SDK Server Guide: Rotate Videos
+ *
+ * Demonstrates video rotation in headless mode:
+ * - Setting rotation angles in radians
+ * - Converting between degrees and radians
+ * - Getting current rotation values
+ * - Locking rotation on specific blocks
+ * - Saving scenes for later rendering
+ *
+ * Note: Full video export (MP4) requires the CE.SDK Renderer.
+ * In headless Node.js mode, we save the scene for later use.
+ */
+
+// 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 scene with a page
+  const scene = engine.scene.create('DepthStack');
+  const page = engine.block.create('page');
+  engine.block.setWidth(page, 800);
+  engine.block.setHeight(page, 500);
+  engine.block.appendChild(scene, page);
+
+  // Sample video URL for demonstrations
+  const videoUri = 'https://img.ly/static/ubq_video_samples/bbb.mp4';
+
+  // Block size for layout
+  const blockSize = { width: 200, height: 150 };
+
+  // Helper functions for angle conversion
+  const toRadians = (degrees: number) => (degrees * Math.PI) / 180;
+  const toDegrees = (radians: number) => (radians * 180) / Math.PI;
+
+  // Demo 1: Rotated Video - 45 degree rotation
+  console.log('Loading video 1 of 3...');
+  const rotatedVideo = await engine.block.addVideo(
+    videoUri,
+    blockSize.width,
+    blockSize.height
+  );
+  engine.block.appendChild(page, rotatedVideo);
+  engine.block.setPositionX(rotatedVideo, 50);
+  engine.block.setPositionY(rotatedVideo, 100);
+  console.log('✓ Video 1 loaded');
+
+  // Rotate the video 45 degrees (convert to radians)
+  engine.block.setRotation(rotatedVideo, toRadians(45));
+
+  // Add label for rotated video
+  const text1 = engine.block.create('text');
+  engine.block.setString(text1, 'text/text', '45° Rotation');
+  engine.block.setFloat(text1, 'text/fontSize', 28);
+  engine.block.setEnum(text1, 'text/horizontalAlignment', 'Center');
+  engine.block.setWidth(text1, 200);
+  engine.block.setPositionX(text1, 50);
+  engine.block.setPositionY(text1, 280);
+  engine.block.appendChild(page, text1);
+
+  // Get current rotation value
+  const currentRotation = engine.block.getRotation(rotatedVideo);
+  console.log('Current rotation:', toDegrees(currentRotation), 'degrees');
+
+  // Demo 2: 90 Degree Rotation
+  console.log('Loading video 2 of 3...');
+  const rotatedVideo90 = await engine.block.addVideo(
+    videoUri,
+    blockSize.width,
+    blockSize.height
+  );
+  engine.block.appendChild(page, rotatedVideo90);
+  engine.block.setPositionX(rotatedVideo90, 300);
+  engine.block.setPositionY(rotatedVideo90, 100);
+  console.log('✓ Video 2 loaded');
+
+  // Rotate 90 degrees using Math.PI / 2
+  engine.block.setRotation(rotatedVideo90, Math.PI / 2);
+
+  // Add label for 90 degree rotation
+  const text2 = engine.block.create('text');
+  engine.block.setString(text2, 'text/text', '90° Rotation');
+  engine.block.setFloat(text2, 'text/fontSize', 28);
+  engine.block.setEnum(text2, 'text/horizontalAlignment', 'Center');
+  engine.block.setWidth(text2, 200);
+  engine.block.setPositionX(text2, 300);
+  engine.block.setPositionY(text2, 280);
+  engine.block.appendChild(page, text2);
+
+  // Demo 3: Locked Rotation - Rotation is disabled for this block
+  console.log('Loading video 3 of 3...');
+  const lockedVideo = await engine.block.addVideo(
+    videoUri,
+    blockSize.width,
+    blockSize.height
+  );
+  engine.block.appendChild(page, lockedVideo);
+  engine.block.setPositionX(lockedVideo, 550);
+  engine.block.setPositionY(lockedVideo, 150);
+  console.log('✓ Video 3 loaded');
+
+  // Disable rotation for this specific block
+  engine.block.setScopeEnabled(lockedVideo, 'layer/rotate', false);
+
+  // Add label for locked video
+  const text3 = engine.block.create('text');
+  engine.block.setString(text3, 'text/text', 'Rotation Locked');
+  engine.block.setFloat(text3, 'text/fontSize', 28);
+  engine.block.setEnum(text3, 'text/horizontalAlignment', 'Center');
+  engine.block.setWidth(text3, 200);
+  engine.block.setPositionX(text3, 550);
+  engine.block.setPositionY(text3, 320);
+  engine.block.appendChild(page, text3);
+
+  // Check if rotation is enabled for a block
+  const canRotate = engine.block.isScopeEnabled(lockedVideo, 'layer/rotate');
+  console.log('Rotation enabled:', canRotate);
+
+  // Save the scene to preserve the rotated videos
+  // Note: Video export (MP4/PNG with video frames) requires the CE.SDK Renderer.
+  // In headless Node.js mode, we save the scene file which can be loaded later
+  // in a browser environment or rendered with the CE.SDK Renderer.
+  console.log('Saving scene...');
+
+  const sceneString = await engine.scene.saveToString();
+
+  // Ensure output directory exists
+  if (!existsSync('output')) {
+    mkdirSync('output');
   }
-}
 
-export default Example;
+  // Save scene to file
+  writeFileSync('output/rotate-videos.scene', sceneString);
+  console.log('Saved to output/rotate-videos.scene');
+
+  // Log final rotation values to verify
+  console.log('Video rotations:');
+  console.log(
+    `  Rotated video (45°): ${toDegrees(engine.block.getRotation(rotatedVideo)).toFixed(1)}°`
+  );
+  console.log(
+    `  Rotated video (90°): ${toDegrees(engine.block.getRotation(rotatedVideo90)).toFixed(1)}°`
+  );
+  console.log(
+    `  Locked video: ${toDegrees(engine.block.getRotation(lockedVideo)).toFixed(1)}° [Rotation locked]`
+  );
+
+  console.log('Video rotation guide completed successfully.');
+} finally {
+  // Always dispose the engine to free resources
+  engine.dispose();
+}
 ```
 
 This guide covers rotating videos programmatically, converting between degrees and radians, grouping blocks for collective rotation, and locking rotation permissions.
 
+<NodejsVideoExportNotice {...props} />
+
+## Initialize Headless Engine
+
+Create a headless engine instance for programmatic video manipulation:
+
+```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)
+});
+```
+
+## Create the Scene
+
+Create a scene with specific page dimensions:
+
+```typescript highlight-create-scene
+// Create a scene with a page
+const scene = engine.scene.create('DepthStack');
+const page = engine.block.create('page');
+engine.block.setWidth(page, 800);
+engine.block.setHeight(page, 500);
+engine.block.appendChild(scene, page);
+```
+
+## Converting Degrees and Radians
+
+CE.SDK uses radians for rotation values. Create helper functions to convert between degrees and radians:
+
+```typescript highlight-convert-angles
+const toRadians = (degrees: number) => (degrees * Math.PI) / 180;
+const toDegrees = (radians: number) => (radians * 180) / Math.PI;
+```
+
 ## Rotating Videos
 
 Rotate videos using `engine.block.setRotation()` with the angle in radians. Convert from degrees using the formula `radians = degrees * Math.PI / 180`:
 
 ```typescript highlight-rotate-video
-// Rotate the video 45 degrees (in radians)
-const toRadians = (degrees: number) => (degrees * Math.PI) / 180;
+// Rotate the video 45 degrees (convert to radians)
 engine.block.setRotation(rotatedVideo, toRadians(45));
 ```
 
@@ -246,7 +237,6 @@ Read the current rotation value using `engine.block.getRotation()`. The value is
 ```typescript highlight-get-rotation
 // Get current rotation value
 const currentRotation = engine.block.getRotation(rotatedVideo);
-const toDegrees = (radians: number) => (radians * 180) / Math.PI;
 console.log('Current rotation:', toDegrees(currentRotation), 'degrees');
 ```
 
@@ -278,35 +268,82 @@ const canRotate = engine.block.isScopeEnabled(lockedVideo, 'layer/rotate');
 console.log('Rotation enabled:', canRotate);
 ```
 
+## Save Scene
+
+Save the scene to a file. The scene can later be loaded in a browser environment or rendered with the CE.SDK Renderer for full video export:
+
+```typescript highlight-export
+  // Save the scene to preserve the rotated videos
+  // Note: Video export (MP4/PNG with video frames) requires the CE.SDK Renderer.
+  // In headless Node.js mode, we save the scene file which can be loaded later
+  // in a browser environment or rendered with the CE.SDK Renderer.
+  console.log('Saving scene...');
+
+  const sceneString = await engine.scene.saveToString();
+
+  // Ensure output directory exists
+  if (!existsSync('output')) {
+    mkdirSync('output');
+  }
+
+  // Save scene to file
+  writeFileSync('output/rotate-videos.scene', sceneString);
+  console.log('Saved to output/rotate-videos.scene');
+
+  // Log final rotation values to verify
+  console.log('Video rotations:');
+  console.log(
+    `  Rotated video (45°): ${toDegrees(engine.block.getRotation(rotatedVideo)).toFixed(1)}°`
+  );
+  console.log(
+    `  Rotated video (90°): ${toDegrees(engine.block.getRotation(rotatedVideo90)).toFixed(1)}°`
+  );
+  console.log(
+    `  Locked video: ${toDegrees(engine.block.getRotation(lockedVideo)).toFixed(1)}° [Rotation locked]`
+  );
+```
+
+## Cleanup
+
+Always dispose the engine to free resources when done:
+
+```typescript highlight-cleanup
+// Always dispose the engine to free resources
+engine.dispose();
+```
+
 ## Troubleshooting
 
 ### Rotation Has No Effect
 
 Verify the block exists in the scene and is not a page block. Check if rotation is locked using `engine.block.isScopeEnabled(block, 'layer/rotate')`.
 
-### Rotation Handle Missing
-
-Check if rotation handles are hidden globally via `controlGizmo/showRotateHandles` setting. Verify the `'layer/rotate'` scope is enabled for the block.
-
 ### Unexpected Rotation Direction
 
 Remember that positive values rotate counterclockwise in CE.SDK. To rotate clockwise, use negative radian values.
 
 ## API Reference
 
-| Method                              | Description                            |
-| ----------------------------------- | -------------------------------------- |
-| `engine.block.setRotation()`        | Set block rotation in radians          |
-| `engine.block.getRotation()`        | Get current rotation in radians        |
-| `engine.block.setScopeEnabled()`    | Enable/disable `'layer/rotate'` scope  |
-| `engine.block.isScopeEnabled()`     | Check if rotation is allowed           |
-| `engine.block.setTransformLocked()` | Lock all transforms including rotation |
+| Method                             | Description                                               |
+| ---------------------------------- | --------------------------------------------------------- |
+| `CreativeEngine.init()`            | Initializes the headless engine for programmatic creation |
+| `engine.scene.create()`            | Creates a new scene                                       |
+| `engine.block.findByType()`        | Finds blocks by type                                      |
+| `engine.block.setRotation()`       | Set block rotation in radians                             |
+| `engine.block.getRotation()`       | Get current rotation in radians                           |
+| `engine.block.setScopeEnabled()`   | Enable/disable `'layer/rotate'` scope                     |
+| `engine.block.isScopeEnabled()`    | Check if rotation is allowed                              |
+| `engine.block.setTransformLocked()`| Lock all transforms including rotation                    |
+| `engine.scene.saveToString()`      | Save scene to string for later use                        |
+| `engine.dispose()`                 | Dispose engine and free 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