jpegpleno

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 30, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package jpegpleno provides decoding support for JPEG Pleno.

Authoritative standard: ISO/IEC 21794 (published umbrella; the JPEG-Pleno Framework originally circulated under the track-P designation ISO/IEC 19997 — the two refer to the same SC29/WG1 committee work at different stages).

JPEG Pleno is a family of standards for plenoptic imaging, covering:

  • Part 2: Light field coding with 4D-PM (Prediction Mode) and 4D-TM (Transform Mode)
  • Part 5: Holography - binary and continuous-tone hologram coding
  • Part 6: Point cloud coding using learning-based approaches

This package provides common types and utilities shared across all JPEG Pleno modalities. Specific implementations are in sub-packages:

  • jpegpleno/lightfield: 4D light field decoding
  • jpegpleno/holography: Hologram decoding
  • jpegpleno/pointcloud: 3D point cloud decoding

Security

All decoders enforce security limits from the security package:

  • Max4DDimensions: Maximum dimension size for 4D light field data
  • MaxLightFieldViews: Maximum number of views in a light field
  • MaxPointCloudPoints: Maximum number of points in a point cloud

Coordinate Systems

JPEG Pleno uses several coordinate systems:

Light Field (4D): Uses (u, v, s, t) coordinates where:

  • (u, v) are angular coordinates identifying the viewpoint
  • (s, t) are spatial coordinates within each view

Hologram: Uses (x, y) plane coordinates for hologram pixels, with additional parameters for wavelength and pixel pitch.

Point Cloud: Uses (x, y, z) Cartesian coordinates for 3D points, optionally with color (r, g, b) and normal vectors (nx, ny, nz).

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrInvalidHeader indicates the JPEG Pleno header is malformed or invalid.
	ErrInvalidHeader = errors.New("invalid JPEG Pleno header")

	// ErrUnsupportedVersion indicates an unsupported JPEG Pleno version.
	ErrUnsupportedVersion = errors.New("unsupported JPEG Pleno version")

	// ErrTruncatedData indicates the data is incomplete or truncated.
	ErrTruncatedData = errors.New("truncated JPEG Pleno data")

	// ErrInvalidDimensions indicates invalid dimension values.
	ErrInvalidDimensions = errors.New("invalid JPEG Pleno dimensions")

	// ErrDimensionsTooLarge indicates dimensions exceed security limits.
	ErrDimensionsTooLarge = errors.New("JPEG Pleno dimensions exceed maximum limit")

	// ErrInvalidCoordinates indicates invalid coordinate values.
	ErrInvalidCoordinates = errors.New("invalid JPEG Pleno coordinates")

	// ErrCoordinatesOutOfRange indicates coordinates are outside valid bounds.
	ErrCoordinatesOutOfRange = errors.New("JPEG Pleno coordinates out of range")
)

Common errors shared across all JPEG Pleno modalities.

View Source
var (
	// ErrInvalidLightField indicates the light field data is malformed.
	ErrInvalidLightField = errors.New("invalid light field data")

	// ErrUnsupportedLightFieldMode indicates an unsupported light field coding mode.
	ErrUnsupportedLightFieldMode = errors.New("unsupported light field coding mode")

	// ErrTooManyViews indicates the view count exceeds security limits.
	ErrTooManyViews = errors.New("light field view count exceeds maximum limit")

	// ErrInvalidViewCoordinates indicates invalid (u, v) view coordinates.
	ErrInvalidViewCoordinates = errors.New("invalid light field view coordinates")

	// ErrViewNotFound indicates the requested view does not exist.
	ErrViewNotFound = errors.New("light field view not found")

	// ErrInvalidAngularResolution indicates invalid angular resolution.
	ErrInvalidAngularResolution = errors.New("invalid light field angular resolution")

	// ErrInvalidSlantParameters indicates invalid slant parameters for slanted 4D-TM.
	ErrInvalidSlantParameters = errors.New("invalid light field slant parameters")

	// ErrInvalidPredictionMode indicates an invalid 4D-PM prediction mode.
	ErrInvalidPredictionMode = errors.New("invalid light field prediction mode")

	// ErrInvalidTransformMode indicates an invalid 4D-TM transform mode.
	ErrInvalidTransformMode = errors.New("invalid light field transform mode")

	// ErrDisparityOutOfRange indicates disparity values exceed allowed range.
	ErrDisparityOutOfRange = errors.New("light field disparity out of range")
)

Light field specific errors (Part 2).

View Source
var (
	// ErrInvalidHologram indicates the hologram data is malformed.
	ErrInvalidHologram = errors.New("invalid hologram data")

	// ErrUnsupportedHologramType indicates an unsupported hologram type.
	ErrUnsupportedHologramType = errors.New("unsupported hologram type")

	// ErrInvalidWaveField indicates invalid wave field data.
	ErrInvalidWaveField = errors.New("invalid wave field data")

	// ErrInvalidWavelength indicates an invalid wavelength parameter.
	ErrInvalidWavelength = errors.New("invalid hologram wavelength")

	// ErrInvalidPixelPitch indicates an invalid pixel pitch parameter.
	ErrInvalidPixelPitch = errors.New("invalid hologram pixel pitch")

	// ErrInvalidComplexData indicates invalid complex-valued hologram data.
	ErrInvalidComplexData = errors.New("invalid complex hologram data")

	// ErrInvalidPropagationParams indicates invalid propagation parameters.
	ErrInvalidPropagationParams = errors.New("invalid hologram propagation parameters")

	// ErrHologramTooLarge indicates hologram dimensions exceed limits.
	ErrHologramTooLarge = errors.New("hologram dimensions exceed maximum limit")
)

Holography specific errors (Part 5).

View Source
var (
	// ErrInvalidPointCloud indicates the point cloud data is malformed.
	ErrInvalidPointCloud = errors.New("invalid point cloud data")

	// ErrTooManyPoints indicates the point count exceeds security limits.
	ErrTooManyPoints = errors.New("point cloud point count exceeds maximum limit")

	// ErrInvalidGeometry indicates invalid geometry stream data.
	ErrInvalidGeometry = errors.New("invalid point cloud geometry data")

	// ErrInvalidAttributes indicates invalid attribute stream data.
	ErrInvalidAttributes = errors.New("invalid point cloud attribute data")

	// ErrInvalidBoundingBox indicates an invalid bounding box.
	ErrInvalidBoundingBox = errors.New("invalid point cloud bounding box")

	// ErrInvalidPointCoordinates indicates invalid 3D point coordinates.
	ErrInvalidPointCoordinates = errors.New("invalid point cloud point coordinates")

	// ErrInvalidNormalVector indicates an invalid normal vector.
	ErrInvalidNormalVector = errors.New("invalid point cloud normal vector")

	// ErrUnsupportedCompressionMode indicates an unsupported point cloud compression mode.
	ErrUnsupportedCompressionMode = errors.New("unsupported point cloud compression mode")

	// ErrReconstructionFailed indicates learning-based reconstruction failed.
	ErrReconstructionFailed = errors.New("point cloud reconstruction failed")
)

Point cloud specific errors (Part 6).

Functions

This section is empty.

Types

type BoundingBox3D

type BoundingBox3D struct {
	// Min is the minimum corner of the bounding box.
	Min Point3DCoord

	// Max is the maximum corner of the bounding box.
	Max Point3DCoord
}

BoundingBox3D represents an axis-aligned bounding box in 3D space.

func (*BoundingBox3D) Center

func (b *BoundingBox3D) Center() Point3DCoord

Center returns the center point of the bounding box.

func (*BoundingBox3D) Contains

func (b *BoundingBox3D) Contains(point *Point3DCoord) bool

Contains returns true if the point is within the bounding box.

func (*BoundingBox3D) Size

func (b *BoundingBox3D) Size() Point3DCoord

Size returns the dimensions of the bounding box.

func (*BoundingBox3D) Validate

func (b *BoundingBox3D) Validate() error

Validate checks that the bounding box is valid (min <= max for all axes).

type Color3D

type Color3D struct {
	// R is the red component [0, 255].
	R uint8

	// G is the green component [0, 255].
	G uint8

	// B is the blue component [0, 255].
	B uint8
}

Color3D represents an RGB color for a point.

type ColorSpace

type ColorSpace uint8

ColorSpace defines the color space of plenoptic data.

const (
	// ColorSpaceUnknown indicates an unspecified color space.
	ColorSpaceUnknown ColorSpace = 0

	// ColorSpaceRGB indicates RGB color space.
	ColorSpaceRGB ColorSpace = 1

	// ColorSpaceYCbCr indicates YCbCr color space.
	ColorSpaceYCbCr ColorSpace = 2

	// ColorSpaceGray indicates grayscale.
	ColorSpaceGray ColorSpace = 3

	// ColorSpaceRGBA indicates RGBA with alpha channel.
	ColorSpaceRGBA ColorSpace = 4
)

func (ColorSpace) String

func (c ColorSpace) String() string

String returns a human-readable name for the color space.

type Header struct {
	// Version is the JPEG Pleno version number.
	Version uint16

	// Type indicates the type of plenoptic content.
	Type PlenoType

	// Flags contains various header flags.
	Flags uint8

	// Reserved bytes for future use.
	Reserved [4]byte
}

Header represents the common JPEG Pleno file header.

func (*Header) Validate

func (h *Header) Validate() error

Validate checks that the header values are within acceptable ranges.

type HologramDimensions

type HologramDimensions struct {
	// Width is the hologram width in pixels.
	Width int

	// Height is the hologram height in pixels.
	Height int

	// PixelPitch is the physical pixel pitch in meters (typically micrometers).
	PixelPitch float64

	// Wavelength is the recording wavelength in meters (typically nanometers).
	Wavelength float64
}

HologramDimensions represents the dimensions of a hologram.

func (*HologramDimensions) ContainsCoord

func (d *HologramDimensions) ContainsCoord(coord *HologramPlaneCoord) bool

ContainsCoord returns true if the given coordinate is within bounds.

func (*HologramDimensions) PhysicalHeight

func (d *HologramDimensions) PhysicalHeight() float64

PhysicalHeight returns the physical height of the hologram in meters.

func (*HologramDimensions) PhysicalWidth

func (d *HologramDimensions) PhysicalWidth() float64

PhysicalWidth returns the physical width of the hologram in meters.

func (*HologramDimensions) PixelCount

func (d *HologramDimensions) PixelCount() (int, error)

PixelCount returns the total number of pixels in the hologram.

func (*HologramDimensions) Validate

func (d *HologramDimensions) Validate() error

Validate checks that the dimensions are within security limits.

type HologramPlaneCoord

type HologramPlaneCoord struct {
	// X is the horizontal coordinate on the hologram plane.
	X int

	// Y is the vertical coordinate on the hologram plane.
	Y int
}

HologramPlaneCoord represents a 2D coordinate on the hologram plane.

func (*HologramPlaneCoord) ToIndex

func (c *HologramPlaneCoord) ToIndex(width int) (int, error)

ToIndex converts the 2D coordinate to a linear array index.

func (*HologramPlaneCoord) Validate

func (c *HologramPlaneCoord) Validate(width, height int) error

Validate checks that the coordinates are within bounds.

type LightFieldCoord4D

type LightFieldCoord4D struct {
	// U is the horizontal angular coordinate (viewpoint column).
	U int

	// V is the vertical angular coordinate (viewpoint row).
	V int

	// S is the horizontal spatial coordinate (pixel column within view).
	S int

	// T is the vertical spatial coordinate (pixel row within view).
	T int
}

LightFieldCoord4D represents a 4D coordinate in a light field. The light field is parameterized as L(u, v, s, t) where:

  • (u, v) are angular coordinates (viewpoint position)
  • (s, t) are spatial coordinates (pixel position within a view)

func (*LightFieldCoord4D) IsZero

func (c *LightFieldCoord4D) IsZero() bool

IsZero returns true if all coordinates are zero.

func (*LightFieldCoord4D) Validate

func (c *LightFieldCoord4D) Validate() error

Validate checks that the coordinates are within security limits.

type LightFieldDimensions

type LightFieldDimensions struct {
	// AngularU is the number of views in the U (horizontal) direction.
	AngularU int

	// AngularV is the number of views in the V (vertical) direction.
	AngularV int

	// SpatialS is the width of each view in pixels.
	SpatialS int

	// SpatialT is the height of each view in pixels.
	SpatialT int
}

LightFieldDimensions represents the dimensions of a 4D light field.

func (*LightFieldDimensions) Contains4DCoord

func (d *LightFieldDimensions) Contains4DCoord(coord *LightFieldCoord4D) bool

Contains4DCoord returns true if the given 4D coordinate is valid.

func (*LightFieldDimensions) ContainsPixelCoord

func (d *LightFieldDimensions) ContainsPixelCoord(s, t int) bool

ContainsPixelCoord returns true if the given (s, t) coordinates are valid.

func (*LightFieldDimensions) ContainsViewCoord

func (d *LightFieldDimensions) ContainsViewCoord(u, v int) bool

ContainsViewCoord returns true if the given (u, v) coordinates are valid.

func (*LightFieldDimensions) TotalPixelCount

func (d *LightFieldDimensions) TotalPixelCount() (int64, error)

TotalPixelCount returns the total number of pixels in the entire light field.

func (*LightFieldDimensions) TotalViews

func (d *LightFieldDimensions) TotalViews() (int, error)

TotalViews returns the total number of views in the light field.

func (*LightFieldDimensions) Validate

func (d *LightFieldDimensions) Validate() error

Validate checks that the dimensions are within security limits.

func (*LightFieldDimensions) ViewPixelCount

func (d *LightFieldDimensions) ViewPixelCount() (int, error)

ViewPixelCount returns the number of pixels in a single view.

type Normal3D

type Normal3D struct {
	// NX is the X component of the normal.
	NX float32

	// NY is the Y component of the normal.
	NY float32

	// NZ is the Z component of the normal.
	NZ float32
}

Normal3D represents a 3D normal vector.

func (*Normal3D) IsNormalized

func (n *Normal3D) IsNormalized(tolerance float32) bool

IsNormalized returns true if the normal has unit length (within tolerance).

func (*Normal3D) IsZero

func (n *Normal3D) IsZero() bool

IsZero returns true if the normal is a zero vector.

type PlenoMetadata

type PlenoMetadata struct {
	// Type indicates the type of plenoptic content.
	Type PlenoType

	// Version is the JPEG Pleno specification version.
	Version string

	// ColorSpace is the color space of the data.
	ColorSpace ColorSpace

	// BitDepth is the bit depth per sample.
	BitDepth int

	// ComponentCount is the number of color components.
	ComponentCount int

	// CreationDate is the creation timestamp (Unix time).
	CreationDate int64

	// Description is an optional human-readable description.
	Description string
}

PlenoMetadata contains common metadata for JPEG Pleno files.

func (*PlenoMetadata) Validate

func (m *PlenoMetadata) Validate() error

Validate checks that the metadata is valid.

type PlenoType

type PlenoType uint8

PlenoType identifies the type of JPEG Pleno content.

const (
	// PlenoTypeLightField indicates light field data (Part 2).
	PlenoTypeLightField PlenoType = 1

	// PlenoTypeHologram indicates hologram data (Part 5).
	PlenoTypeHologram PlenoType = 2

	// PlenoTypePointCloud indicates point cloud data (Part 6).
	PlenoTypePointCloud PlenoType = 3
)

func (PlenoType) IsValid

func (t PlenoType) IsValid() bool

IsValid returns true if the type is a recognized JPEG Pleno type.

func (PlenoType) String

func (t PlenoType) String() string

String returns a human-readable name for the JPEG Pleno type.

type Point3DCoord

type Point3DCoord struct {
	// X is the X coordinate.
	X float32

	// Y is the Y coordinate.
	Y float32

	// Z is the Z coordinate.
	Z float32
}

Point3DCoord represents a 3D coordinate in Cartesian space.

func (*Point3DCoord) Add

func (c *Point3DCoord) Add(other *Point3DCoord) Point3DCoord

Add returns the sum of two 3D coordinates.

func (*Point3DCoord) IsZero

func (c *Point3DCoord) IsZero() bool

IsZero returns true if all coordinates are zero.

func (*Point3DCoord) Scale

func (c *Point3DCoord) Scale(factor float32) Point3DCoord

Scale returns the coordinate scaled by a factor.

func (*Point3DCoord) Sub

func (c *Point3DCoord) Sub(other *Point3DCoord) Point3DCoord

Sub returns the difference of two 3D coordinates.

type PointCloudBounds

type PointCloudBounds struct {
	// BoundingBox is the axis-aligned bounding box enclosing all points.
	BoundingBox BoundingBox3D

	// PointCount is the total number of points.
	PointCount int64

	// HasColors indicates if points have color information.
	HasColors bool

	// HasNormals indicates if points have normal vectors.
	HasNormals bool
}

PointCloudBounds represents the bounds and statistics of a point cloud.

func (*PointCloudBounds) Validate

func (b *PointCloudBounds) Validate() error

Validate checks that the point cloud bounds are valid.

Directories

Path Synopsis
Package holography provides decoding support for JPEG Pleno Holography.
Package holography provides decoding support for JPEG Pleno Holography.
Package lightfield provides types and decoding for JPEG Pleno Light Field.
Package lightfield provides types and decoding for JPEG Pleno Light Field.
Package pointcloud provides types and decoding for JPEG Pleno Point Cloud.
Package pointcloud provides types and decoding for JPEG Pleno Point Cloud.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL