iiifimageapi

README

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.

Example

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

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

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()

License

MIT License

Documentation

Index

• Constants
• Variables
• type ComplianceLevelName
• type ComplianceLevelSpec
• type ComplianceLevels
• type FeatureName
• type FeatureNameList
  • func (fnl FeatureNameList) Sort()
• type FeatureNotSupportedError
  • func (e FeatureNotSupportedError) Error() string
• type ImageInformation
  • func NewImageInformation(info ImageInformation) ImageInformation
• type ImageInformationSize
• type ImageInformationTile
• type InvalidValueError
  • func NewInvalidValueError(s string) InvalidValueError
  • func (e InvalidValueError) Error() string

Constants

const (
	Context  = "http://iiif.io/api/image/3/context.json"
	Type     = "ImageService3"
	Protocol = "http://iiif.io/api/image"
)

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"
)

Variables

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

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

Types

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