package module
v0.0.0-...-064f8e4 Latest Latest

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

Go to latest
Published: Feb 12, 2024 License: MIT Imports: 3 Imported by: 0


A package focused on low-level data types and behaviors for the IIIF Image API (v3) specification.

  • parsing {region}/{size}/{rotation}/{quality}.{format} parameter values;
  • validating parameters against advertised compliance levels, maximums, and extra features;
  • resolving relative parameter values against an image profile for absolute pixels;
  • converting parameter values to canonical form;
  • enumerating region+size based on static size or tile configuration; and
  • constructing basic info.json contents.

This package does not perform image processing. Resolved parameters should typically be used for performing upstream or RPC requests to dedicated image servers.

Learn more from code documentation, examples, or *_test.go files.


The following example is based on examples/parse/main.go. Import the packages...

import (
	iiifimageapi "github.com/dpb587/go-iiif-image-api-v3"

And then use any of the functions necessary to process the request...

// Params are the raw values, typically received as paths of an HTTP request.
var params = imagerequest.RawParams{"pct:25,25,50,50", "max", "90", "color.png"}

// ParseParams extracts typed values from the raw parameters of an image
// request and ensure they are valid values per the specification.
parsedParams, err := imagerequest.ParseRawParams(params)
if err != nil {
  log.Fatalf("parsing params: %v", err)

// Resolve validates parameters according to a specific image (e.g. profile/
// feature support, region/size bounds), and converts any relative values into
// an absolute form (e.g. pct:* to pixels, size upscaling, and quality).
resolvedParams, err := parsedParams.Resolve(imagerequest.ResolveOptions{
  ImageInformation: iiifimageapi.ImageInformation{
    Profile: iiifimageapi.ComplianceLevel2Name,
    Width:   3024,
    Height:  4032,
  DefaultQuality: "color",
if err != nil {
  log.Fatalf("resolving params: %v", err)

// Optionally refer to the canonical form of parameters (per specification).
canonicalParams := resolvedParams.Canonical()


MIT License




View Source
const (
	Context  = "http://iiif.io/api/image/3/context.json"
	Type     = "ImageService3"
	Protocol = "http://iiif.io/api/image"
View Source
const (
	ComplianceLevel0Name            ComplianceLevelName = "level0"
	ComplianceLevel0ProfileDocument string              = "http://iiif.io/api/image/3/level0.json"

	ComplianceLevel1Name            ComplianceLevelName = "level1"
	ComplianceLevel1ProfileDocument string              = "http://iiif.io/api/image/3/level1.json"

	ComplianceLevel2Name            ComplianceLevelName = "level2"
	ComplianceLevel2ProfileDocument string              = "http://iiif.io/api/image/3/level2.json"


View Source
var OfficialComplianceLevels = officialComplianceLevels{
	ComplianceLevel0Name: complianceLevel0Spec,
	ComplianceLevel1Name: complianceLevel1Spec,
	ComplianceLevel2Name: complianceLevel2Spec,

OfficialComplianceLevels is the official levels defined by the spec. DefaultComplianceLevels should typically be used instead.


This section is empty.


type ComplianceLevelName

type ComplianceLevelName string

type ComplianceLevelSpec

type ComplianceLevelSpec interface {
	Name() ComplianceLevelName
	ProfileDocument() string

	BaseFeatures() FeatureNameList
	BaseQualities() []string
	BaseFormats() []string

type ComplianceLevels

type ComplianceLevels interface {
	GetByName(name ComplianceLevelName) (ComplianceLevelSpec, bool)
var DefaultComplianceLevels ComplianceLevels = OfficialComplianceLevels

DefaultComplianceLevels is a shared set of compliance levels that may be reconfigured. By default it is the set of levels defined in the specification.

type FeatureName

type FeatureName string
const (
	// FeatureNameBaseUriRedirect means the base URI of the service will redirect to the image information document.
	FeatureNameBaseUriRedirect FeatureName = "baseUriRedirect"

	// FeatureNameCanonicalLinkHeader means the canonical image URI HTTP link header is provided on image responses.
	FeatureNameCanonicalLinkHeader FeatureName = "canonicalLinkHeader"

	// FeatureNameCors means the CORS HTTP headers are provided on all responses.
	FeatureNameCors FeatureName = "cors"

	// FeatureNameJsonldMediaType means the JSON-LD media type is provided when requested.
	FeatureNameJsonldMediaType FeatureName = "jsonldMediaType"

	// FeatureNameMirroring means the image may be rotated around the vertical axis, resulting in a left-to-right mirroring of the content.
	FeatureNameMirroring FeatureName = "mirroring"

	// FeatureNameProfileLinkHeader means the profile HTTP link header is provided on image responses.
	FeatureNameProfileLinkHeader FeatureName = "profileLinkHeader"

	// FeatureNameRegionByPct means regions of the full image may be requested by percentage.
	FeatureNameRegionByPct FeatureName = "regionByPct"

	// FeatureNameRegionByPx means regions of the full image may be requested by pixel dimensions.
	FeatureNameRegionByPx FeatureName = "regionByPx"

	// FeatureNameRegionSquare means a square region may be requested, where the width and height are equal to the shorter dimension of the full image.
	FeatureNameRegionSquare FeatureName = "regionSquare"

	// FeatureNameRotationArbitrary means image rotation may be requested using values other than multiples of 90 degrees.
	FeatureNameRotationArbitrary FeatureName = "rotationArbitrary"

	// FeatureNameRotationBy90s means image rotation may be requested in multiples of 90 degrees.
	FeatureNameRotationBy90s FeatureName = "rotationBy90s"

	// FeatureNameSizeByConfinedWh means image size may be requested in the form !w,h.
	FeatureNameSizeByConfinedWh FeatureName = "sizeByConfinedWh"

	// FeatureNameSizeByH means image size may be requested in the form ,h.
	FeatureNameSizeByH FeatureName = "sizeByH"

	// FeatureNameSizeByPct means images size may be requested in the form pct:n.
	FeatureNameSizeByPct FeatureName = "sizeByPct"

	// FeatureNameSizeByW means image size may be requested in the form w,.
	FeatureNameSizeByW FeatureName = "sizeByW"

	// FeatureNameSizeByWh means image size may be requested in the form w,h.
	FeatureNameSizeByWh FeatureName = "sizeByWh"

	// FeatureNameSizeUpscaling means image sizes prefixed with ^ may be requested.
	FeatureNameSizeUpscaling FeatureName = "sizeUpscaling"

type FeatureNameList

type FeatureNameList []FeatureName

func (FeatureNameList) Sort

func (fnl FeatureNameList) Sort()

type FeatureNotSupportedError

type FeatureNotSupportedError FeatureName

FeatureNotSupportedError indicates an input constraint would have required a feature that is not supported.

func (FeatureNotSupportedError) Error

func (e FeatureNotSupportedError) Error() string

type ImageInformation

type ImageInformation struct {
	Context  string              `json:"@context"`
	ID       string              `json:"id"`
	Type     string              `json:"type"`
	Protocol string              `json:"protocol"`
	Profile  ComplianceLevelName `json:"profile"`

	Width  uint32 `json:"width"`
	Height uint32 `json:"height"`

	Sizes []ImageInformationSize `json:"sizes,omitempty"`
	Tiles []ImageInformationTile `json:"tiles,omitempty"`

	PreferredFormats []string `json:"preferredFormats,omitempty"`

	ExtraQualities []string        `json:"extraQualities,omitempty"`
	ExtraFormats   []string        `json:"extraFormats,omitempty"`
	ExtraFeatures  FeatureNameList `json:"extraFeatures,omitempty"`

	MaxHeight *uint32 `json:"maxHeight,omitempty"`
	MaxWidth  *uint32 `json:"maxWidth,omitempty"`
	MaxArea   *uint32 `json:"maxArea,omitempty"`

	Rights  string        `json:"rights,omitempty"`
	PartOf  []interface{} `json:"partOf,omitempty"`
	SeeAlso []interface{} `json:"seeAlso,omitempty"`
	Service []interface{} `json:"service,omitempty"`

func NewImageInformation

func NewImageInformation(info ImageInformation) ImageInformation

NewImageInformation is a light wrapper to add the default, spec-defined properties: context, type, and protocol.

type ImageInformationSize

type ImageInformationSize struct {
	Width  uint32 `json:"width"`
	Height uint32 `json:"height"`

type ImageInformationTile

type ImageInformationTile struct {
	Width        uint32   `json:"width"`
	Height       uint32   `json:"height,omitempty"`
	ScaleFactors []uint32 `json:"scaleFactors"`

type InvalidValueError

type InvalidValueError struct {
	// contains filtered or unexported fields

InvalidValueError indicates a problem with an input constraint. For HTTP runtimes, this translates to an HTTP 400 Bad Request.

func NewInvalidValueError

func NewInvalidValueError(s string) InvalidValueError

func (InvalidValueError) Error

func (e InvalidValueError) Error() string


Path Synopsis
imagerequest offers functions to parse, validate, and resolve image parameters into more usable forms.
imagerequest offers functions to parse, validate, and resolve image parameters into more usable forms.
pixelset offers functions to enumerate and check region+size values which may be supported through static configuration or based on [spec.ImageInformation].
pixelset offers functions to enumerate and check region+size values which may be supported through static configuration or based on [spec.ImageInformation].

Jump to

Keyboard shortcuts

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