Tuesday, October 11, 2011

Image Sizes in BHL. SEE ALSO: Piece of String, Length of.

“How long is a piece of string?” isn’t a familiar idiom to those living in the Midwest of the continental United States. Well, it wasn’t to at least one person living in the Midwest. It’s the answer you’ll get in the BHL AU office to questions like “How long does it take to build a website?” or any other question to which there isn’t a definitive answer for the general case, like “How big is a page image in BHL?”

Of course another way of answering would be “It depends”. To take two completely random examples, this page from Prodromus of the zoology of Victoria is 1828 pixels wide by 2879 pixels high. This page from Australian Lepidoptera and their transformations is 3496 pixels wide by 4785 pixels high.

Now, I’m sure you’ve gotten familiar with BHL’s API while you’ve been putting together your entry for the Life and Literature code challenge. I know you’re working hard on your entry, ‘cause it’s what all the other cool kids are doing.

You don’t need me to tell you that when you use the API to get an item’s metadata with the page flag set to true, you get a url for a thumbnail image and an url for the full size of each page. Which is fantastic, if you want an image that will fit into a 200px by 300px box, or an IOUS (image of unusual size). What if you want an images that will fit into a 600px by 800px box? Do you get the thumbnail and scale it up? Yes, but only if you’re doing it in a bad police procedural that creates image information from nowhere. In the real world, you need to get the full size image and downsize it. Until now.

Now you can get your Astacoides serratus at a range of sizes to suit your budget. Simply add the width and height of your bounding box at the end of the thumbnail image url, and Bob's your uncle. So, if you want an image to fit into a 600px by 800px box, instead of using the thumbnail url as is (, use,600,800 and you’ll get back an image that’s exactly 914px by 1440px.

Okay, I know that a 914px by 1440px image doesn’t fit into a 600px by 800px box. You’re still going to have to scale the image down to 508px by 800px to fit, but at least you only have to download a third of the information compared to the full size image (148kB vs 436kB). So why aren't we providing an image of A. serratus at 508px by 800px?

Rather than have the server scale the full size image for each request, images are available at fixed fractions of the original dimensions. The fractions available are a half, a quarter, an eighth and a 16th. Those are fractions of the width and height, so each step down has only a quarter as many pixels as the one before.

The server will give you the smallest image available that won’t need to be scaled up to fit within your bounds. So, using our old mate A. serratus as the example, if you specified a bounding box of 915px x 1441px, you'd get the full size image at 1828px x 2879px. If you don’t provide a width and height, the assumed size of the bounding box is 200px by 300px.

I’ve got to be honest, while all the links point to the Australian node, the heavy lifting for this was done by the good folks at You can replace with and get exactly the same results.

Have fun playing with the images, and I look forward to seeing how you put it to good use.