IIIF Size Confined Box Factor Tool

Description

Fit an image into a supplied bounding box while preserving aspect ratio.

IIIF-related selectors describe image regions, canvas coordinates and media intervals. A local arithmetic helper can use a restricted syntax or rounding convention while a full IIIF request must satisfy the API and server behavior.

Fit an image into a supplied bounding box while preserving aspect ratio.

When to use this tool

Use IIIF Size Confined Box Factor when checking the stated image-region, scaling or media-range convention.

How to use the tool and how it works

Enter width, height, boxWidth, boxHeight, allowUpscale. Use the units and conventions below.
Run the tool. Correct any format, range, or cross-field input error before interpreting the output.
Read factor, outputWidth, outputHeight. Use the output convention below.

Fit an image into a supplied bounding box while preserving aspect ratio. Require positive dimensions; factor = min(boxWidth/width,boxHeight/height), capped at one unless allowUpscale. Return factor and scaled dimensions.^[1]

IIIF distinguishes image size constraints and upscaling behavior. The returned factor is local arithmetic, without a server request or pixel rounding.^[2]

Input field	Meaning and units	Accepted input
width	Extent on the stated coordinate or temporal basis.	Required. Finite number; strictly above 0.
height	Height	Required. Finite number; strictly above 0.
boxWidth	Box Width	Required. Finite number; strictly above 0.
boxHeight	Box Height	Required. Finite number; strictly above 0.
allowUpscale	Allow Upscale	Required. Boolean.

Output field	Interpretation	Returned shape
factor	Factor	Required. Finite number.
outputWidth	Output Width	Required. Finite number.
outputHeight	Output Height	Required. Finite number.

json

{
  "input": {
    "width": 400,
    "height": 200,
    "boxWidth": 100,
    "boxHeight": 100,
    "allowUpscale": false
  },
  "output": {
    "factor": 0.25,
    "outputWidth": 100,
    "outputHeight": 50
  }
}

Limitations and assumptions

Dimensions remain numeric without pixel rounding; no IIIF request or actual image is generated.
Inputs must satisfy both the field types and the cross-field conditions above. Invalid input causes an error; a successful false flag or documented placeholder is a different result.
Numeric calculations use binary floating point unless exact decimal-integer arithmetic is explicitly stated. No hidden measurement tolerance or decimal rounding is added; nonfinite or out-of-contract results are rejected. Numeric signed-zero results are exported as zero.

Alternative or Complementary methods

Use a conforming IIIF client and actual manifest or image information for complete request validation and resource access.

References

Calculation and input contract: digital-humanities/iiif-size-confined-box-factor — tool.io
IIIF Image API 3.0: size — IIIF Consortium

Similar or alternative tools

Digital Humanities: IIIF Xywh Region Token
Parse a restricted IIIF-style xywh token.
IIIF Selector Reference Gap
Return normalized selector-reference coordinate gaps.