Name: iiif_url
Owner: NCSU Libraries
Description: Create and parse IIIF Image API URLs
Created: 2016-03-13 00:56:46.0
Updated: 2016-03-13 02:42:47.0
Pushed: 2016-08-30 21:44:49.0
Homepage: null
Size: 17
Language: Ruby
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
Create and parse IIIF Image API URLs
Add this line to your application's Gemfile:
'iiif_url'
And then execute:
$ bundle
Or install it yourself as:
$ gem install iiif_url
Here's the simplest case of creating a IIIF URL with all params. By default only the path is given without the scheme, server, port, or IIIF prefix.
_base_url = "http://example.edu/prefix"
ms = {
entifier: 'abc',
gion: 'full',
ze: 'full',
tation: 0,
ality: 'default',
rmat: 'jpg'
= IiifUrl.from_params(params)
"/abc/full/full/0/default.jpg"
_url = File.join(iiif_base_url, url)
"http://example.edu/prefix/full/full/0/default.jpg"
If the base URL is set then it will form a full URL automatically:
Url.set_base_url("http://example.edu/prefix")
ms = {
entifier: 'abc',
gion: 'full',
ze: 'full',
tation: 0,
ality: 'default',
rmat: 'jpg'
= IiifUrl.from_params(params)
"http://example.edu/prefix/abc/full/full/0/default.jpg"
You can also pass in the base URL in with the params, which will override any value set for the base URL.
Url.set_base_url("http://example.edu/prefix")
ms = {
entifier: 'abc',
se_url: "http://example.org",
gion: 'full',
ze: 'full',
tation: 0,
ality: 'default',
rmat: 'jpg'
= IiifUrl.from_params(params)
"http://example.org/abc/full/full/0/default.jpg"
If the base URL is set you can prevent it being used and just return the path portion by setting the base_url
option key to false
:
Url.set_base_url("http://example.edu/prefix")
ms = {
entifier: 'abc',
se_url: false,
gion: 'full',
ze: 'full',
tation: 0,
ality: 'default',
rmat: 'jpg'
= IiifUrl.from_params(params)
"/abc/full/full/0/default.jpg"
A more complicated region and size:
ms = {
entifier: 'abc',
gion: {
x: 0,
y: 0,
w: 1000,
h: 1200
ze: {w: 300},
tation: 0,
ality: 'default',
rmat: 'jpg'
= IiifUrl.from_params(params)
"/abc/0,0,1000,1200/300,/0/default.jpg"
To use a percent region or percent size, you must prefix the keys like this:
ms = {
entifier: 'abc',
gion: {
pctx: 10,
pcty: 10,
pctw: 80,
pcth: 80
ze: {pct: 50}
= IiifUrl.from_params(params)
"/abc/pct:10,10,80,80/pct:50/0/default.jpg"
If no identifier is passed in, then only the IIIF URL path will be returned:
ms = {
ze: {pct: 50}
= IiifUrl.from_params(params)
"/full/pct:50/0/default.jpg"
Even if a base_url is given if there is no identifier, then only the IIIF URL path will be returned:
ms = {
se_url: "http://example.org/prefix/",
ze: {pct: 50}
= IiifUrl.from_params(params)
"/full/pct:50/0/default.jpg"
You only need to specify values that are different from the defaults. The defaults are as specified:
| parameter | value | |:———–|:———-| | identifier | null | | region | “full” | | size | “full” | | rotation | “0” | | quality | “default” | | format | “jpg” |
ms = {
entifier: 'abc',
ze: {w: 600}
= IiifUrl.from_params(params)
"/abc/full/600,/0/default.jpg"
And without an identifier:
ms = {
ze: {w: 600}
= IiifUrl.from_params(params)
"/full/600,/0/default.jpg"
There may be cases where you do not have all of the params you need so you want to pass around a IiifUrl to add more params.
= IiifUrl.new
region({x:100, y:200, w: 300, h: 300})
size({w: 150}).format('png')
to_s
"/100,200,300,300/150,/0/default.png"
You can also pass in some initial params and then add on others:
= IiifUrl.new({size: {w: 100}})
identifier('abc')
format('png')
rotation(180)
to_s
"/abc/full/100,/180/default.png"
IIIF URLs are parsed by segments including: region, size, rotation, quality, and format. The region and size segments can also be parsed into a string or hash. Rotation is always parsed into a hash. Quality and format are always a string.
Simple case for region and size parsed into strings:
ms = IiifUrl.parse("/full/full/0/default.png")
{region: "full", size: "full", rotation: {degrees: 0, mirror: false}, quality: 'default', format: 'png'}
With an identifier:
ms = IiifUrl.parse("/abc/full/full/0/default.png")
{identifier: "abc", region: "full", size: "full", rotation: {degrees: 0, mirror: false}, quality: 'default', format: 'png'}
Parameterized region and size:
ms = IiifUrl.parse("/0,100,200,300/75,/0/default.jpg")
{identifier: nil, region: {x:0, y:100, w: 200, h: 300}, size: {w: 75, h: nil}, rotation: {degrees: 0, mirror: false}, quality: "default", format: "jpg" }
Parse a full URL:
ms = IiifUrl.parse("http://example.org/prefix/abc/0,100,200,300/75,/0/default.jpg")
{identifier: abc, region: {x:0, y:100, w: 200, h: 300}, size: {w: 75, h: nil}, rotation: {degrees: 0, mirror: false}, quality: "default", format: "jpg" }
No validation is done for creating or parsing a URL. This allows for extensions to the IIIF Image API.
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/NCSU-Libraries/iiif_url.
Jason Ronallo
The gem is copyright North Carolina State University and is available as open source under the terms of the MIT License.