Image Elements

Complete reference for image elements with the Zvid, including filters, effects, cropping, and chroma key functionality.

Overview

Image elements allow you to add static images to your videos with extensive customization options including filters, cropping, chroma key (green screen), border radius, and various visual effects.

ImageItem Interface

interface ImageItem {
  type: "IMAGE";
  src: string;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  anchor?: Anchor;
  position?: PositionPreset;
  resize?: ResizeMode;
  enterBegin?: number;
  enterEnd?: number;
  exitBegin?: number;
  exitEnd?: number;
  track?: number;
  opacity?: number;
  angle?: number;
  flipV?: boolean;
  flipH?: boolean;
  enterAnimation?: string | undefined;
  exitAnimation?: string | undefined;
  filter?: FilterOptions;
  cropParams?: CropParams;
  chromaKey?: { color: string; similarity?: number; blend?: number };
  radius?: BorderRadius;
  zoom?: boolean;
}

Properties

Required Properties

Property	Type	Description
type	"IMAGE"	Element type identifier
src	string	Image file path or URL

Position & Size Properties

Property	Type	Default	Description
x	number	0	Horizontal position in pixels
y	number	0	Vertical position in pixels
width	number	Source width	Image width in pixels
height	number	Source height	Image height in pixels
position	PositionPreset	"custom"	Position preset (overrides x, y)
anchor	Anchor	"top-left"	Anchor point for positioning
resize	ResizeMode	undefined	Resize mode (overrides width, height)

Timing Properties

Property	Type	Default	Description
enterBegin	number	0	Start time for entrance (seconds)
enterEnd	number	0	End time for entrance animation (seconds)
exitBegin	number	project.duration	Start time for exit animation (seconds)
exitEnd	number	project.duration	End time for exit (seconds)

Visual Properties

Property	Type	Default	Description
track	number	0	Layer/track number (higher = on top)
opacity	number	1	Transparency (0-1)
angle	number	0	Rotation in degrees
flipV	boolean	false	Flip Vertically
flipH	boolean	false	Flip Horizontal
zoom	boolean	false	Enables a center-based zoom effect

Animation Properties

Property	Type	Description
enterAnimation	string | undefined	Entrance animation name
exitAnimation	string | undefined	Exit animation name

Effect Properties

Property	Type	Description
filter	FilterOptions	Image filters and effects
cropParams	CropParams	Cropping configuration
chromaKey	ChromaKey	Chroma key color for green screen
radius	BorderRadius	Border radius for rounded corners

ChromaKey interface

interface ChromaKey {
  color: string;
  similarity?: number;
  blend?: number;
}

PositionPreset

type PositionPreset =
  | "top-left"
  | "top-center"
  | "top-right"
  | "center-left"
  | "center-center"
  | "center-right"
  | "bottom-right"
  | "bottom-center"
  | "bottom-left"
  | "custom";

ResizeMode

type ResizeMode = "contain" | "cover";

Anchor

export type Anchor =
  | "top-left"
  | "top-center"
  | "top-right"
  | "center-left"
  | "center-center"
  | "center-right"
  | "bottom-left"
  | "bottom-center"
  | "bottom-right";

FilterOptions Interface

interface FilterOptions {
  brightness?: number;
  contrast?: number;
  "hue-rotate"?: string;
  saturate?: number;
  blur?: string;
}

Filter Properties

Property	Type	Range	Description
brightness	number	-100 to 100	Brightness input (mapped to -1..1)
contrast	number	-100 to 100	Contrast input (mapped to 0..1 or 1..1000)
hue-rotate	string | number	0 to 360 (deg)	Hue rotation (e.g. "90deg" or 90)
saturate	number	-100 to 100	Saturation input (mapped to 0..1 or 1..3)
blur	string | number	0 to 100	Blur strength as percent (mapped to 0..shortestDim/2)
invert	boolean | number	false/true or 0 to 1	Invert (boolean = full, number = strength)
colorTint	string	"#000000" to "#ffffff"	Tint color in hex (#rrggbb)

CropParams Interface

interface CropParams {
  // horizontal start position (px)
  x: number;
  // vertical start position (px)
  y: number;
  // cropped width (px)
  width: number;
  // cropped height (px)
  height: number;
}

Crop Properties

Property	Type	Description
x	number	Crop start X position in source image
y	number	Crop start Y position in source image
width	number	Crop width in pixels
height	number	Crop height in pixels

BorderRadius Interface

interface BorderRadius {
  tl: number; // top-left
  tr: number; // top-right
  bl: number; // bottom-left
  br: number; // bottom-right
}

Zoom Property

The zoom property adds a zoom effect to image elements.
When enabled, the image will smoothly zoom toward its center during its visible duration.

Usage

// Boolean usage (uses default settings)
zoom: true;

Basic Examples

Simple Image

{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2022/08/16/05/50/straw-bales-7389396_1280.jpg",
  x: 100,
  y: 100,
  width: 400,
  height: 300
}

Image with Position Preset

{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2025/07/12/12/54/scarlet-robin-9710532_960_720.jpg",
  width: 500,
  height: 400,
  position: "center-center", // Automatically centers the image
  enterBegin: 0,
  enterEnd: 1,
  exitBegin: 9,
  exitEnd: 10,
  enterAnimation: "fade",
  exitAnimation: "fade"
}

Image with Resize Mode

{
    type: "IMAGE",
    src: "https://cdn.pixabay.com/photo/2024/10/02/18/24/leaf-9091894_1280.jpg",
    resize: "contain"
}

Advanced Examples

Cropped Image

{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2023/06/04/20/21/cat-8040862_1280.jpg",
  x: 300,
  y: 200,
  width: 400,
  height: 300,
  cropParams: {
    x: 100,    // Start crop 100px from left
    y: 50,     // Start crop 50px from top
    width: 800, // Crop 800px wide
    height: 600 // Crop 600px tall
  },
}

Green Screen (Chroma Key)

{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2024/10/02/18/24/leaf-9091894_1280.jpg",
  x: 0,
  y: 0,
  width: 1280,
  height: 720,
  chromaKey: {
    color: "#D9950B",
    similarity: 30,
  }, // Green color to remove
  track: 1
}

Rounded Corners

{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2022/11/05/22/11/channel-7572879_1280.jpg",
  x: 50,
  y: 50,
  width: 200,
  height: 200,
  radius: {
    tl: 20, // top-left radius
    tr: 20, // top-right radius
    bl: 20, // bottom-left radius
    br: 20  // bottom-right radius
  },
}

Rotated and Flipped Image

{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2022/08/16/05/50/straw-bales-7389396_1280.jpg",
  position: "center-center",
  width: 600,
  height: 377,
  angle: 45,           // Rotate 45 degrees
  flipH: true,         // Flip horizontally
  opacity: 0.8,
  track: 5,
  anchor: "center-center" // default; try "top-left" or "bottom-right" to change rotation/scale origin
}

Complex Examples

Artistic Filter Combination

{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2023/06/04/20/21/cat-8040862_1280.jpg",
  x: 0,
  y: 0,
  width: 1280,
  height: 720,
  filter: {
    brightness: 10,
    "hue-rotate": "30deg",
    blur: "2px"
  },
}

Picture-in-Picture Effect

{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2024/10/02/18/24/leaf-9091894_1280.jpg",
  position: "bottom-right",
  width: 300,
  height: 200,
  radius: {
    tl: 10, tr: 10, bl: 10, br: 10
  },
  track: 10, // High track to appear on top
}

Supported Image Formats

All Supported FFMPEG formats are accepted.

Some examples:

• JPEG/JPG - Best for photographs
• PNG - Best for images with transparency
• WebP - Modern format with good compression

Best Practices

Performance Optimization

1. Image Size: Use appropriately sized images to avoid unnecessary scaling
2. Format Selection: Use JPEG for photos, PNG for graphics with transparency
3. Compression: Optimize images before use to reduce file size
4. Caching: URLs are cached automatically for better performance

Visual Quality

1. Aspect Ratio: Maintain aspect ratio when scaling to avoid distortion
2. Filter Moderation: Use subtle filter values for natural-looking results
3. Layer Management: Use track numbers strategically for proper layering

Chroma Key Tips

1. Even Lighting: Ensure even lighting on green screen for best results
2. Similarity Adjustment: Start with low similarity and increase as needed
3. Color Selection: Use exact hex color of your green screen background

Common Patterns

Background Image

{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2022/08/16/05/50/straw-bales-7389396_1280.jpg",
  x: 0, y: 0,
  width: 1280, height: 720,
  track: 0, // Background layer
  filter: { brightness: -20 } // Slightly darker for text overlay
}

Overlay Graphics

{
    type: "IMAGE",
    src: "https://cdn.pixabay.com/photo/2024/10/02/18/24/leaf-9091894_1280.jpg",
    x: 100,
    y: 100,
    width: 150,
    height: 100,
    track: 5,
    enterBegin: 0,
    enterEnd: 1,
    exitBegin: 4,
    exitEnd: 5,
    opacity: 0.8,
    enterAnimation: "fade",
    exitAnimation: "fade"
}

Image Gallery Effect

// Multiple images with staggered animations
{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2023/06/04/20/21/cat-8040862_1280.jpg",
  x: 100, y: 100, width: 300, height: 200,
  enterAnimation: "slideleft",
  enterBegin: 0, enterEnd: 1
},
{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2022/08/16/05/50/straw-bales-7389396_1280.jpg",
  x: 450, y: 100, width: 300, height: 200,
  enterAnimation: "slideleft",
  enterBegin: 0.5, enterEnd: 1.5
},
{
  type: "IMAGE",
  src: "https://cdn.pixabay.com/photo/2022/11/05/22/11/channel-7572879_1280.jpg",
  x: 800, y: 100, width: 300, height: 200,
  enterAnimation: "slideleft",
  enterBegin: 1, enterEnd: 2
}

Related Pages

• Video Elements - Working with video files
• Animation Effects - Animating your images
• SVG Elements - Vector graphics and shapes

Next Steps

• Video Elements - Add video content to your projects
• Animation with precise timing controls - Learn about image animations