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 ¶
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.
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.
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 ¶
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 (*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 (*Parser) ParseMetaBin ¶
ParseMetaBin parses a metadata-bin from response data.
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 (*Response) AddDataBin ¶
AddDataBin adds or updates a data-bin with new data.
func (*Response) GetBinStatus ¶
GetBinStatus returns status for all data-bins.
func (*Response) GetDataBin ¶
GetDataBin returns the data-bin for the given class, codestream, and ID.
func (*Response) GetMainHeader ¶
GetMainHeader returns the main header data-bin.
func (*Response) GetMetaBin ¶
GetMetaBin returns the metadata-bin for the given ID.