Image Elements

Complete reference for image elements in the Zvid Package, 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;
  position?: PositionPreset;
  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 | null;
  exitAnimation?: string | null;
  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	"center-center"	Anchor point for positioning
resize	ResizeMode	null	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

Animation Properties

Property	Type	Default	Description
enterAnimation	string | null	null	Entrance animation name
exitAnimation	string | null	null	Exit animation name

Effect Properties

Property	Type	Default	Description
filter	FilterOptions	{}	Image filters and effects
cropParams	CropParams	null	Cropping configuration
chromaKey	ChromaKey	{}	Chroma key color for green screen
radius	BorderRadius	null	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;
  [key: string]: string | number | undefined;
}

Filter Properties

Property	Type	Range	Description
brightness	number	0-2+	Brightness level (1 = normal)
contrast	number	0-2+	Contrast level (1 = normal)
hue-rotate	string	"0deg"-"360deg"	Hue rotation
saturate	number	0-2+	Saturation level (1 = normal)
blur	string	"0px"-"50px"	Blur radius

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
}

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
• GIF - Static images only (use GIF elements for animated GIFs)
• SVG - Vector graphics (use SVG elements for better control)

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
• Animwith precise timing controts - Learn about image animations