{"id":77,"date":"2018-06-16T03:38:03","date_gmt":"2018-06-16T03:38:03","guid":{"rendered":"https:\/\/embers.nicejacket.cc\/blog\/?p=77"},"modified":"2018-06-16T03:57:07","modified_gmt":"2018-06-16T03:57:07","slug":"transparent-layers-for-openseadragon-with-libvips","status":"publish","type":"post","link":"https:\/\/embers.nicejacket.cc\/blog\/2018\/06\/16\/transparent-layers-for-openseadragon-with-libvips\/","title":{"rendered":"Transparent Layers for OpenSeadragon with libvips"},"content":{"rendered":"

One major issue in making the map<\/a> of the Embers was creating transparent layers. I wanted my map to have borders reminiscent of John Speed<\/a>‘s wonderful maps, but the process of OpenSeadragon<\/a>-ing with transparent pngs can be tricky.<\/p>\n

<\/p>\n

\"John<\/a>
Map of Wales, John Speed (Wikipedia<\/a>)<\/figcaption><\/figure>\n

Look at the map above. The borders are essentially at 50% opacity. You don’t lose detail beneath them and I feel they blend well into the map, especially for my mood setting-first approach.<\/p>\n

At the time of writing, there’s a bug in OpenSeadragon which causes a slight overlap apparent in layers made from transparent images, even when overlay=0 in your dzi file. Thankfully this bug has been fixed<\/a> in the master branch, but it isn’t released quite yet.<\/p>\n

\"transparent
This is a mockup, but essentially what you’d see if one of your dzi layers was based off a transparent image.<\/figcaption><\/figure>\n

Regardless, I believe best practice when you need transparent layers is to make your shapes\/images at 100% opacity with transparent backgrounds, and manage opacity in your OpenSeadragon tileSource settings:<\/p>\n

\"better
Solid images + transparent background = happy worldbuilder.<\/figcaption><\/figure>\n

So, how to do that.<\/p>\n

Borders with libvips: Labor of Love, Emphasis on Labor.<\/h5>\n

In my previous post<\/a>, I showed an easy way to compose large images from smaller tiles using ImageMagick, but here the mogrify process will convert transparency to white. You can reverse this<\/a>, but you’re left with pixel residue. There are ways to work around that<\/a>, but if I wanted fuzzy borders, I would have drawn them that way.<\/p>\n

libvips is the superior tool here. On my todo list is writing a script to automate this process in libvips, but at the time I was dumb and just wanted to finish my map. The process below is for those who might have trouble scripting this process but still want a map. More time for you to learn about brilliant worldbuilding minutia like albedo<\/a>.<\/p>\n

In your Illustrator\/Photoshop\/GIMP file, hide all non-border layers. Unlike my previous post<\/a>, we can’t use ImageMagick, so you can’t svg > png. You have to save your border tile artboards as png manually. I found naming them cartesianally (see below) helps keeping your mind straight, and I’ll use this methodology below.<\/span><\/p>\n

\"cartesian<\/p>\n

Documentation on merge is here<\/a>. In terminal, navigate to where vips.exe lives, and run the following:<\/p>\n

$ vips merge c:\\1-2.png c:\\1-1.png c:\\row1output1.png horizontal 3000 0<\/pre>\n
The order might seem counterintuitive; vips is saying, “give me the image you want to add (1-2.png), and then the source<\/em> you want me to add it to (1-1.png)”. Merge horizontally, and the position you want the “added” image offset. In my case, tiles are 3000×3000, so I want 1-2.png offset 3000 pixels from (0,0) of my source<\/em> 1-1.png.<\/p>\n
Thus, to get the 1-3.png added:<\/p>\n
$ vips merge c:\\1-3.png c:\\row1output1.png c:\\row1output2.png horizontal 6000 0<\/pre>\n
Once you’ve reached the end of your row, I recommend starting a new row from scratch with the above method. That way if you enter the wrong coordinates you only have to fix or redo that row.<\/p>\n
Once you have all your complete row images, merge them vertically:<\/p>\n
$ vips merge c:\\row2.png c:\\row1.png c:\\outputrows12.png vertical 0 3000<\/pre>\n
Repeat as necessary.<\/p>\n
You can save some time by skipping empty spaces, as merge will fill this in. My map’s artboards aren’t a perfect grid:<\/p>\n
\"artboard<\/p>\n
So when I got to my third row, I offset the third row 6000 down and 3000 over:<\/p>\n
$ vips merge c:\\row3.png c:\\rows1and2.png c:\\rows123.png vertical 3000 6000<\/pre>\n
Once you have your transparent border layer, run dzsave normally<\/a> (using –suffix .png to maintain file format), and you’ll have a transparent dzi.<\/p>\n
If you now want the opaque elements of your transparency layer to appear somewhat transparent in OpenSeadragon, include the opacity option in tileSources:<\/p>\n
...\r\ntileSources: [\r\n{\r\n  tileSource: 'dzi\/basemap.dzi',\r\n  opacity: 1\r\n},\r\n{\r\n  tileSource: 'dzi\/borders.dzi',\r\n  opacity: 0.5\r\n}\r\n...<\/pre>\n
Lastly, as this process is laborious and less than ideal, if your transparency layer is smaller than your base maps, you can position it with x and y, though if the layer doesn’t match the width of the base dzi, you’ll need to position it using width and height or it will stretch to match. You can read more about this here<\/a>. For example:<\/p>\n
...\r\n{\r\n  tileSource: 'dzi\/borders.dzi.',\r\n  opacity: 0.5,\r\n  x: 0.33,\r\n  y: 0.75,\r\n  width: 0.2,\r\n  height: 0.25\r\n}\r\n...<\/pre>\n","protected":false},"excerpt":{"rendered":"
One major issue in making the map of the Embers was creating transparent layers. I wanted my map to have borders reminiscent of John Speed‘s wonderful maps, but the process of OpenSeadragon-ing with transparent pngs can be tricky.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-77","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/embers.nicejacket.cc\/blog\/wp-json\/wp\/v2\/posts\/77","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/embers.nicejacket.cc\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/embers.nicejacket.cc\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/embers.nicejacket.cc\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/embers.nicejacket.cc\/blog\/wp-json\/wp\/v2\/comments?post=77"}],"version-history":[{"count":6,"href":"https:\/\/embers.nicejacket.cc\/blog\/wp-json\/wp\/v2\/posts\/77\/revisions"}],"predecessor-version":[{"id":92,"href":"https:\/\/embers.nicejacket.cc\/blog\/wp-json\/wp\/v2\/posts\/77\/revisions\/92"}],"wp:attachment":[{"href":"https:\/\/embers.nicejacket.cc\/blog\/wp-json\/wp\/v2\/media?parent=77"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/embers.nicejacket.cc\/blog\/wp-json\/wp\/v2\/categories?post=77"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/embers.nicejacket.cc\/blog\/wp-json\/wp\/v2\/tags?post=77"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}