jpip

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: 4 Imported by: 0

Documentation

Overview

Package jpip implements JPEG 2000 Part 9 (JPIP) client response parsing as specified in ISO/IEC 15444-9.

JPIP (JPEG 2000 Interactive Protocol) enables interactive access to JPEG 2000 images over networks. This package focuses on client-side response parsing, allowing applications to reconstruct images from JPIP server responses.

Architecture

JPIP uses a bin-based data model where image data is organized into:

  • Data-bins: Portions of the JPEG 2000 codestream (precincts, tiles, etc.)
  • Meta-bins: Metadata associated with the image
  • Main Header: Contains the main codestream header data

Response Format

JPIP responses contain a series of messages, each describing a portion of the image data. This package parses these responses and provides mechanisms to reconstruct the original codestream data.

Incremental Updates

JPIP supports incremental image delivery. Clients can receive partial data and progressively refine the image quality. This package tracks received data and supports incremental updates.

Usage

The JPIP response parser integrates with network clients. After receiving a JPIP response from a server, the parser extracts data-bins that can be used to reconstruct the JPEG 2000 codestream.

Security

All operations validate input bounds and use safe integer conversions from the internal/safeconv package. The parser enforces security limits to prevent denial-of-service attacks.

References

  • ISO/IEC 15444-9:2005 - JPEG 2000 image coding system: Interactivity tools, APIs and protocols
  • ITU-T Rec. T.808 (2005)

Index

Constants

View Source
const (
	// ClassPrecinct identifies precinct data-bins.
	ClassPrecinct uint8 = 0

	// ClassTileHeader identifies tile header data-bins.
	ClassTileHeader uint8 = 1

	// ClassTileData identifies tile data-bins (without headers).
	ClassTileData uint8 = 2

	// ClassMainHeader identifies the main codestream header data-bin.
	ClassMainHeader uint8 = 6

	// ClassMetadata identifies metadata-bins.
	ClassMetadata uint8 = 8
)

Data-bin class identifiers per ISO/IEC 15444-9.

View Source
const (
	// MaxDataBins is the maximum number of data-bins per response.
	MaxDataBins = 65536

	// MaxBinSize is the maximum size of a single data-bin in bytes.
	MaxBinSize = 64 * 1024 * 1024 // 64 MB

	// MaxVBASBytes is the maximum bytes for a VBAS value.
	MaxVBASBytes = 8

	// MaxCodestreams is the maximum number of codestreams.
	MaxCodestreams = 256
)

Maximum limits for validation.

View Source
const (
	// FlagLastByte indicates this is the last message for the data-bin.
	FlagLastByte uint8 = 0x01

	// FlagCodestreamIndex indicates a codestream index is present.
	FlagCodestreamIndex uint8 = 0x02

	// FlagAuxiliary indicates auxiliary data is present.
	FlagAuxiliary uint8 = 0x04

	// FlagExtended indicates extended header format.
	FlagExtended uint8 = 0x08
)

Message flags for JPIP message headers.

Variables

View Source
var (
	// ErrInvalidResponse indicates the JPIP response is malformed.
	ErrInvalidResponse = errors.New("jpip: invalid response")

	// ErrDataBinError indicates an error parsing a data-bin.
	ErrDataBinError = errors.New("jpip: data-bin parsing error")

	// ErrMetaBinError indicates an error parsing a meta-bin.
	ErrMetaBinError = errors.New("jpip: meta-bin parsing error")

	// ErrTruncatedData indicates the response data is incomplete.
	ErrTruncatedData = errors.New("jpip: truncated response data")

	// ErrInvalidBinClass indicates an invalid data-bin class was specified.
	ErrInvalidBinClass = errors.New("jpip: invalid bin class")

	// ErrInvalidCodestreamIndex indicates an invalid codestream index.
	ErrInvalidCodestreamIndex = errors.New("jpip: invalid codestream index")

	// ErrBinOverflow indicates a data-bin size overflow.
	ErrBinOverflow = errors.New("jpip: bin size overflow")

	// ErrMaxBinsExceeded indicates too many data-bins were received.
	ErrMaxBinsExceeded = errors.New("jpip: maximum bins exceeded")

	// ErrIncompleteMainHeader indicates the main header is incomplete.
	ErrIncompleteMainHeader = errors.New("jpip: incomplete main header")

	// ErrInvalidVBAS indicates an invalid VBAS encoding.
	ErrInvalidVBAS = errors.New("jpip: invalid VBAS encoding")

	// ErrUnsupportedVersion indicates an unsupported JPIP version.
	ErrUnsupportedVersion = errors.New("jpip: unsupported version")
)

JPIP-specific errors for response parsing operations.

Functions

This section is empty.

Types

type BinStatus

type BinStatus struct {
	// Class is the bin class.
	Class uint8

	// BinID is the bin identifier.
	BinID int64

	// BytesReceived is the number of bytes received.
	BytesReceived int64

	// TotalBytes is the total expected bytes (0 if unknown).
	TotalBytes int64

	// IsComplete is true if the bin is complete.
	IsComplete bool
}

BinStatus represents the completion status of a data-bin.

type ClientCache

type ClientCache struct {
	// contains filtered or unexported fields
}

ClientCache represents the client-side data cache for incremental updates.

func NewClientCache

func NewClientCache() *ClientCache

NewClientCache creates a new client cache.

func (*ClientCache) GetBin

func (c *ClientCache) GetBin(class uint8, csIndex int, binID int64) *DataBin

GetBin returns a cached data-bin.

func (*ClientCache) GetMainHeader

func (c *ClientCache) GetMainHeader(csIndex int) []byte

GetMainHeader returns the cached main header.

func (*ClientCache) HasMainHeader

func (c *ClientCache) HasMainHeader(csIndex int) bool

HasMainHeader returns true if the main header is cached and complete.

func (*ClientCache) UpdateFromResponse

func (c *ClientCache) UpdateFromResponse(resp *Response) error

UpdateFromResponse updates the cache with data from a response.

type DataBin

type DataBin struct {
	// Class identifies the type of data-bin.
	Class uint8

	// CodestreamIndex identifies which codestream this bin belongs to.
	CodestreamIndex int

	// BinID is the unique identifier within the class.
	BinID int64

	// Offset is the offset within the bin where this data starts.
	Offset int64

	// Data contains the bin data bytes.
	Data []byte

	// IsComplete is true if the bin is fully received.
	IsComplete bool

	// TotalLength is the total expected length (if known).
	TotalLength int64
}

DataBin represents a JPIP data-bin. Data-bins are portions of the JPEG 2000 codestream identified by class, codestream index, and bin ID.

type Message

type Message struct {
	// BinID identifies the data-bin.
	BinID int64

	// Class identifies the bin class.
	Class uint8

	// CodestreamIndex identifies the codestream.
	CodestreamIndex int

	// Offset is the byte offset within the bin.
	Offset int64

	// Length is the length of the data in this message.
	Length int

	// IsLast is true if this is the final message for the bin.
	IsLast bool

	// Data contains the message payload.
	Data []byte
}

Message represents a single JPIP message in a response.

type MetaBin

type MetaBin struct {
	// BinID is the metadata-bin identifier.
	BinID int64

	// BoxType is the JP2 box type for this metadata.
	BoxType [4]byte

	// Data contains the metadata bytes.
	Data []byte

	// IsComplete is true if the metadata is fully received.
	IsComplete bool
}

MetaBin represents a JPIP metadata-bin.

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser parses JPIP response data.

func NewParser

func NewParser() *Parser

NewParser creates a new JPIP parser.

func (*Parser) ParseMetaBin

func (p *Parser) ParseMetaBin(data []byte) (*MetaBin, error)

ParseMetaBin parses a metadata-bin from response data.

func (*Parser) ParseResponse

func (p *Parser) ParseResponse(data []byte) (*Response, error)

ParseResponse parses a complete JPIP response.

type Reconstructor

type Reconstructor struct {
	// contains filtered or unexported fields
}

Reconstructor reconstructs JPEG 2000 codestreams from JPIP data.

func NewReconstructor

func NewReconstructor() *Reconstructor

NewReconstructor creates a new codestream reconstructor.

func (*Reconstructor) GetDataBin

func (r *Reconstructor) GetDataBin(class uint8, csIndex int, binID int64) *DataBin

GetDataBin returns a specific data-bin.

func (*Reconstructor) GetMainHeader

func (r *Reconstructor) GetMainHeader(csIndex int) ([]byte, error)

GetMainHeader returns the main header for a codestream.

func (*Reconstructor) IsMainHeaderComplete

func (r *Reconstructor) IsMainHeaderComplete(csIndex int) bool

IsMainHeaderComplete returns true if the main header is complete.

func (*Reconstructor) ProcessResponse

func (r *Reconstructor) ProcessResponse(resp *Response) error

ProcessResponse processes a JPIP response and updates the cache.

type Response

type Response struct {
	// Messages contains all parsed messages.
	Messages []*Message

	// DataBins contains accumulated data-bin data.
	DataBins map[dataBinKey]*DataBin

	// MetaBins contains accumulated metadata-bin data.
	MetaBins map[int64]*MetaBin

	// MainHeaderComplete is true if the main header is complete.
	MainHeaderComplete bool

	// TotalBytesReceived tracks total bytes received.
	TotalBytesReceived int64
}

Response represents a parsed JPIP response.

func NewResponse

func NewResponse() *Response

NewResponse creates a new empty JPIP response.

func (*Response) AddDataBin

func (r *Response) AddDataBin(bin *DataBin) error

AddDataBin adds or updates a data-bin with new data.

func (*Response) GetBinStatus

func (r *Response) GetBinStatus() []BinStatus

GetBinStatus returns status for all data-bins.

func (*Response) GetDataBin

func (r *Response) GetDataBin(class uint8, csIndex int, binID int64) *DataBin

GetDataBin returns the data-bin for the given class, codestream, and ID.

func (*Response) GetMainHeader

func (r *Response) GetMainHeader() *DataBin

GetMainHeader returns the main header data-bin.

func (*Response) GetMetaBin

func (r *Response) GetMetaBin(binID int64) *MetaBin

GetMetaBin returns the metadata-bin for the given ID.

Jump to

Keyboard shortcuts

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