Table of Contents

Class GPUVideoEffectEquirectangular360

Namespace
VisioForge.Core.Types.VideoEffects
Assembly
VisioForge.Core.dll

Represents a GPU-accelerated equirectangular 360-degree video effect that converts spherical panoramic video to flat perspective view.

public class GPUVideoEffectEquirectangular360 : GPUVideoEffectVR360Base, IGPUVideoEffectEquirectangular360, IGPUVideoEffectVR360Base, IGPUVideoEffect

Inheritance

Implements

Inherited Members

Remarks

The VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquirectangular360 effect transforms equirectangular (also known as spherical or lat-long) 360-degree video into a flat, viewable perspective. Equirectangular projection is the most common format for 360-degree video, used by platforms like YouTube 360, Facebook 360, and most 360-degree cameras. This format represents the entire sphere as a rectangular image where horizontal position maps to longitude (yaw) and vertical position maps to latitude (pitch). The effect provides interactive camera controls (yaw, pitch, roll, FOV) for navigating through the spherical environment.

SDK Availability

  • Video Capture SDK .Net: Yes
  • Video Edit SDK .Net: Yes
  • Media Player SDK .Net: Yes
  • Media Blocks SDK .Net: Yes

GPU Acceleration

This effect uses custom GPU shaders that perform inverse equirectangular projection in real-time. For each output pixel, the shader computes the corresponding direction vector on the virtual sphere, applies camera rotation transformations (yaw, pitch, roll), and samples the equirectangular source texture at the calculated longitude/latitude coordinates. GPU parallel processing enables 60+ FPS performance at 4K resolution, suitable for smooth interactive VR experiences. Bilinear or bicubic texture filtering ensures high-quality output despite the geometric transformation.

Technical Details

  • Converts equirectangular (lat-long) projection to rectilinear perspective projection
  • Source video spans full 360° horizontal (longitude) and 180° vertical (latitude)
  • Implements inverse spherical-to-cartesian coordinate transformation
  • Applies camera rotation matrix (yaw, pitch, roll) to viewing direction
  • Supports dynamic camera control for interactive viewing experiences
  • FOV parameter controls zoom level and perspective distortion
  • Handles pole discontinuities in equirectangular projection gracefully

Common Use Cases

  • Playing YouTube 360 or Facebook 360 videos with interactive viewing
  • Converting 360-degree camera footage to flat video for editing
  • Creating virtual tours with controllable camera navigation
  • Extracting specific viewpoints from 360° videos for social media
  • Real-time VR video playback with head tracking or mouse control
  • Reframing 360-degree content for traditional 16:9 distribution
  • Interactive panoramic video viewing in desktop applications

Equirectangular Format Characteristics

  • Full sphere mapped to rectangular image (typically 2:1 aspect ratio)
  • Top edge represents "north pole" (looking straight up, pitch +90°)
  • Bottom edge represents "south pole" (looking straight down, pitch -90°)
  • Horizontal center typically faces default forward direction (yaw 0°)
  • Areas near poles show stretching in source (corrected in output projection)
  • Compatible with most 360-degree cameras and platforms

Performance Characteristics

Equirectangular-to-rectilinear projection is computationally efficient on GPU. Each pixel transformation involves a series of trigonometric operations (sin, cos) for coordinate conversion, but GPU hardware acceleration and parallel processing make this viable for real-time use. At 1080p output resolution, frame processing time is typically under 2ms on modern GPUs. At 4K resolution, performance remains real-time (60+ FPS) on mid-range and higher GPUs. Memory bandwidth is optimized through texture caching and efficient sampling patterns.

Camera Control Integration

For interactive VR applications, bind the yaw, pitch, and roll properties to user input:

  • Mouse/Touch: Map horizontal drag to yaw, vertical drag to pitch
  • VR Headset: Read orientation from head tracker (Oculus, HTC Vive, etc.)
  • Gamepad: Right stick for yaw/pitch, triggers for FOV zoom
  • Keyboard: Arrow keys or WASD for discrete camera movements
  • Gyroscope: Mobile device orientation for phone-based VR viewing

Apply smooth interpolation or damping to camera parameter updates to prevent jerky movement and motion sickness.

Integration Tips

  • Verify source video is true equirectangular format (2:1 aspect ratio typical)
  • Start with default FOV of 80-90° for natural, immersive viewing
  • Implement smooth camera transitions to avoid disorientation
  • Consider pole regions have lower resolution in equirectangular source
  • Test with various source resolutions (2K, 4K, 8K) for optimal quality
  • Add on-screen indicators showing current view direction for user orientation

Limitations and Considerations

  • Pole regions (pitch near ±90°) may show artifacts due to source stretching
  • Very wide FOV (>100°) introduces noticeable barrel distortion at edges
  • Source video quality directly impacts output - use high-resolution sources
  • Not compatible with cubemap or other 360° formats - use appropriate effect class

Comparison with Other 360 Formats

Equirectangular is the industry standard for 360-degree video due to its simplicity and widespread support. Alternative formats include cubemap (six square faces) and equiangular cubemap (optimized sampling). For equiangular cubemap sources, use VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquiangularCubemap360 instead. Each format has different storage characteristics and quality trade-offs.

Related Effects

  • VisioForge.Core.Types.VideoEffects.GPUVideoEffectVR360Base: Base class providing common VR 360 functionality
  • VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquiangularCubemap360: For equiangular cubemap format videos

Constructors

GPUVideoEffectEquirectangular360(bool, float, float, float, float, string, TimeSpan, TimeSpan)

Initializes a new instance of the VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquirectangular360 class with specified camera parameters and timing.

public GPUVideoEffectEquirectangular360(bool enabled, float yaw = 0, float pitch = 0, float roll = 0, float fov = 80, string name = "Equirectangular", TimeSpan startTime = default, TimeSpan stopTime = default)

Parameters

enabled bool

true to enable the equirectangular 360 effect immediately; false to create the effect in a disabled state. The effect can be enabled or disabled later using the VisioForge.Core.Types.VideoEffects.GPUVideoEffect.Enabled property.

yaw float

The initial yaw angle in degrees for horizontal camera rotation (0-360°). Default is 0°, facing the front of the equirectangular sphere (horizontal center of the source image). Controls left-right panning direction.

pitch float

The initial pitch angle in degrees for vertical camera rotation (-90 to +90°). Default is 0°, looking at the horizon (vertical center of the source image). Positive values look upward toward the north pole, negative values look downward toward the south pole.

roll float

The initial roll angle in degrees for rotation around viewing axis (-180 to +180°). Default is 0°, maintaining level horizon. Non-zero values create tilted perspective. Typically kept at 0° for comfortable VR viewing.

fov float

The initial field of view angle in degrees (30-120°). Default is 80°, providing balanced immersive viewing without excessive distortion. Lower values zoom in (telephoto), higher values zoom out (wide-angle). Typical range 60-100° for comfortable viewing.

name string

A unique identifier for this effect instance. Defaults to "Equirectangular". This name can be used to retrieve the effect interface from the effect collection for runtime camera control. Use descriptive names when managing multiple camera views (e.g., "MainView", "OverviewCamera", "DetailZoom").

startTime TimeSpan

The time position in the video timeline when this effect should become active. Use Zero (the default) to apply the effect from the beginning of the video. Enables time-based activation for sequences that switch between 360° and flat video modes, or for guided tours with scripted camera paths.

stopTime TimeSpan

The time position in the video timeline when this effect should become inactive. Use Zero (the default) to apply the effect until the end of the video. When combined with startTime, creates time-windowed VR viewing segments within longer video content.

Remarks

This effect transforms equirectangular (spherical/lat-long) 360-degree video into flat rectilinear perspective view using GPU-accelerated projection. All camera parameters (yaw, pitch, roll, FOV) can be updated at runtime for interactive VR experiences. The projection handles the geometric transformation from spherical to planar coordinates while maintaining image quality through bilinear/bicubic texture sampling.

Methods

GetEffectType()

Gets the specific GPU video effect type identifier for this equirectangular 360 effect.

public GPUVideoEffectType GetEffectType()

Returns

GPUVideoEffectType

Returns VisioForge.Core.Types.VideoEffects.GPUVideoEffectType.EquiRectangular360, which uniquely identifies this effect as an equirectangular-to-rectilinear projection effect in the GPU video effects pipeline.

Remarks

This method is used internally by the video processing pipeline to identify and route effects to the appropriate GPU shader implementations. The effect type determines which shader program is executed for performing the equirectangular sphere-to-plane projection transformation.