Usage example for the custom YAML dezoomer

This page describes how to use the tool, following a concrete example.

Stage 1: Find the meta-information associated to your zoomable image

Here is the information we need to find:

the high-resolution image dimensions (width and height in pixels)
the dimensions of the small image tiles (width and height in pixels)

There are several methods for this, depending on the zoomable image service. For the image size, you can try to look for it in the image source, in the resources the page loads, or try to guess, starting with a small value. For the tile sizes, you can use your browser's network monitor to find the tiles, and check their size.

Stage 2: construct the URL template

Here, you need to find the URL format for the tiles. You have to locate the tiles in the network monitor, and copy their URLs. You will probably find out that all tiles have similar URLs, with only a few parameters that change. You will need to guess which parameters represent the x and y position of the tile.

For instance, if our tiles have the following URLs :

http://example.com/my_image/0/0.jpg
http://example.com/my_image/0/1.jpg
...
http://example.com/my_image/12/89.jpg

and the URL template to use is

http://example.com/my_image/{{x}}/{{y}}.jpg

Stage 3: create a `tiles.yaml` file

Open a new blank plain text file in a text editor. You can use Notepad on Windows, TextEdit on MacOS, or Gedit on Linux.

We start by copy-pasting the example tiles.yaml file, and then we modify it:

We set url_template to the url pattern we found in step 2
We set the variables according to what we got in step 1
We set Referer to the URL of the initial web page on which we found the zoomable image.
If we don't have an x and y variables, we use x_template and y_template to specify how to compute the x and y position of each tile.

Then save the file with the name tiles.yaml. Make sure you save it as tiles.yaml and not tiles.yaml.txt. Some text editors tend to add a .txt extension to text files. For instance, in Notepad, you have to select All files (*.*) under Save as type.

How to fill the variable fields

For each variable, dezoomify-rs will generate all of its possible values, going from the indicated from value to the to value, incrementing it by step every time.

For instance { name: x, from: 0, to: 3, step: 1 } will generate the values x=0, x=1, x=2, and x=3,
and { name: x, from: 1, to: 20, step: 5 } will generate the values x=1, x=6, x=11, and x=16.

For each possible combination of variable values, it will create a tile by interpreting the value of the url_template field and downloading an image from it.
Then, it will paste the tile at the value indicated by the x_template and y_template fields. The default value of the x_template field is the variable x, and the default value of the y_template field is the variable y.

Examples

Tile number by axis in the URL

url_template: "http://example.com/my_image/{{x}}/{{y}}.jpg"
x_template: "x * tile_size"
y_template: "y * tile_size"
variables:
  - { name: x, from: 0, to: 2 } # Number of tiles on the x axis
  - { name: y, from: 0, to: 3 } # Number of tiles on the y axis
  - { name: tile_size, value: 256 }
headers:
  Referer: "http://example.com/"

Generated tile URLs

http://example.com/my_image/0/0.jpg	http://example.com/my_image/1/0.jpg	http://example.com/my_image/2/0.jpg
http://example.com/my_image/0/1.jpg	http://example.com/my_image/1/1.jpg	http://example.com/my_image/2/1.jpg
http://example.com/my_image/0/2.jpg	http://example.com/my_image/1/2.jpg	http://example.com/my_image/2/2.jpg
http://example.com/my_image/0/3.jpg	http://example.com/my_image/1/3.jpg	http://example.com/my_image/2/3.jpg

Tile coordinates in pixels in the URL

url_template: "http://example.com/view.php?x={{x}}&y={{y}}"
variables:
  - { name: x, from: 0, to: 512, step: 256 } # Image width, in pixels
  - { name: y, from: 0, to: 768, step: 256 } # Image height, in pixels

Generated tile URLs

http://example.com/view.php?x=0&y=0	http://example.com/view.php?x=256&y=0	http://example.com/view.php?x=512&y=0
http://example.com/view.php?x=0&y=256	http://example.com/view.php?x=256&y=256	http://example.com/view.php?x=512&y=256
http://example.com/view.php?x=0&y=512	http://example.com/view.php?x=256&y=512	http://example.com/view.php?x=512&y=512
http://example.com/view.php?x=0&y=768	http://example.com/view.php?x=256&y=768	http://example.com/view.php?x=512&y=768

Tile index in the url

url_template: "http://example.com/tile_{{i}}.jpg"
x_template: "i % horizontal_tiles"
y_template: "i / horizontal_tiles"
variables:
  - { name: i, from: 0, to: 11 } # Total number of tiles
  - { name: horizontal_tiles, value: 60 } # Number of tiles on the x axis

Generated tile URLs

http://example.com/tile_0.jpg	http://example.com/tile_1.jpg	http://example.com/tile_2.jpg
http://example.com/tile_3.jpg	http://example.com/tile_4.jpg	http://example.com/tile_5.jpg
http://example.com/tile_6.jpg	http://example.com/tile_7.jpg	http://example.com/tile_8.jpg
http://example.com/tile_9.jpg	http://example.com/tile_10.jpg	http://example.com/tile_11.jpg

Stage 4: launch dezoomify-rs

Open a terminal and launch:

dezoomify-rs tiles.yaml result.jpg

Where:

dezoomify-rs is the path to which you downloaded the executable file for your platform,
tiles.yaml is the path to which you saved the file created in the previous step.
result.jpg is the path to the image file you want to create.

Then just wait for the program to finish (this can take some time if the number of tiles to download is large), and open result.jpg: your image should be there !