PIXILAB Wiki

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
blocks:app-note:deepzoom [2021-08-28 14:01] – Text tweaks adminblocks:app-note:deepzoom [2026-02-19 07:34] (current) – Added note about the new Deep Zoom block type admin
Line 1: Line 1:
 =====Deep Zoom===== =====Deep Zoom=====
  
-The term "deep zoom" refers to the ability of displaying extremely high resolution images in a way that allows you to zoom into the image using pinch and pan gestures on a touch screen. This can be used to show, for example, a large map where you can zoom in to read fine print see other details. It's based on a [[https://en.wikipedia.org/wiki/Pyramid_(image_processing)|pyramid representation]] of the original image, dividing it up into multiple layers of increasting resolution. This arrangement makes it possible to handle images that are too large to be managed as is.+:!: **IMPORTANT**: This application note is obsolete. It has been superseded by the Deep Zoom block type introduced in Blocks 7.5, which is now the recommended method for accomplishing this functionality. That block also lets you combine deep zoom with other blocks appearing at selectable zoom depths as well as navigation to/from the Deep Zoom block. 
 +---- 
 + 
 +The term "deep zoom" refers to the ability of displaying extremely high resolution images in a way that allows you to zoom into the image using pinch and pan gestures on a touch screen. This can be used to show, for example, a large map where you can zoom in to read fine print or see other details. It's based on a [[https://en.wikipedia.org/wiki/Pyramid_(image_processing)|pyramid representation]] of the original image, dividing it up into multiple layers of increasing resolution. This arrangement makes it possible to handle images that are too large to be managed as is.
  
 This application note shows how a Web Block can be used to present such deep zoom images. It's based on a small amount of custom html and an image that has been preprocessed using a command line program to create a pyramid representation. This is all embedded into the block itself, as a self contained unit that can be imported to any Blocks server This application note shows how a Web Block can be used to present such deep zoom images. It's based on a small amount of custom html and an image that has been preprocessed using a command line program to create a pyramid representation. This is all embedded into the block itself, as a self contained unit that can be imported to any Blocks server
Line 22: Line 25:
 ====Inside the deep zoom==== ====Inside the deep zoom====
  
-The two blocks demonstrated above bundles a custom web page as well as the pyramidal representation of the image. Normally, you wouldn't open a ZIP file intended to be imported into Blocks. But to learn more about how this block is structured, go ahead and unzip the //deepzoommap.zip// block from above. This is what you'll find:+The two blocks mentioned above bundles a custom web page with the pyramidal representation of the image. Normally, you wouldn't open a ZIP file intended to be imported into Blocks. But if you want to learn more about how this block is structured, go ahead and unzip the //deepzoommap.zip// file downloaded above. This is what you'll find inside:
  
 {{:blocks:app-note:deep-zoom:blockstructure.jpg?600|}} {{:blocks:app-note:deep-zoom:blockstructure.jpg?600|}}
  
-The //Spec.pixi// and //Meta,json// files as well as the //media// directory are standard stuff, while the //custom// directory contains the additional pieces used to render the deep zoom using a Web Block. +The //Spec.pixi// and //Meta,json// files as well as the //media// directory are standard Blocks stuff, while the //custom// directory contains the additional pieces used to render the deep zoom image using a Web Block. This is what's inside: 
  
 {{:blocks:app-note:deep-zoom:customdir.jpg?600|}} {{:blocks:app-note:deep-zoom:customdir.jpg?600|}}
  
- //Index.html// is the HTML file referenced from the Web Block. The web block uses a //relative URL//, beginning with a '~' character. This allows HTML content (as well as custom CSS files) to be embedded inside the block itself in this way, allowing the block and its custom parts to be distributed and imported as a single unit.+The //index.html// file is the HTML code used by the Web Block. The web block references this HTML code using a //relative URL//, beginning with a '~' character. This lets HTML content (as well as custom CSS files) to be embedded inside the block itself, allowing the block and its custom parts to be distributed and imported as a single unit.
  
 Looking more closely at the files in the //custom// directory, you'll see an //openseadragon.min.js// file, which is the javascript that presents and manages the deep zoom image. The //image// folder contains images used to show navigation buttons, if enabled – not the deep zoom images. Those are inside the //out// folder.  Looking more closely at the files in the //custom// directory, you'll see an //openseadragon.min.js// file, which is the javascript that presents and manages the deep zoom image. The //image// folder contains images used to show navigation buttons, if enabled – not the deep zoom images. Those are inside the //out// folder. 
Line 75: Line 78:
 Most of it is just standard HTML stuff, along with with some CSS inside the style tags. The size of the deep zoom image viewer is specified inside the //#openseadragon1// CSS selector shown above.   Most of it is just standard HTML stuff, along with with some CSS inside the style tags. The size of the deep zoom image viewer is specified inside the //#openseadragon1// CSS selector shown above.  
  
-The small amount of javascript code inside the //script// tag initializes the viewer, passing it various options, such as //tileSources// indicating where the image pyramid data is to be found and whether to show //showNavigationControl// (here set to //false// to not show those buttons). +The small amount of javascript code inside the //script// tag initializes the viewer, passing it various options, such as //tileSources// indicating where the image pyramid data is to be found and  //showNavigationControl//, here set to //false// to not show navigation control buttons. 
  
-If you have access to the file system of your Blocks server (e.g., you're running Blocks locally on your laptop), you can locate these files under public/block/<group-name>/deepzoommap/custom/index.html, in case you want to try [[https://openseadragon.github.io/docs/|other options]]. Just open the index.html file with a plain text editor and hack away. Reload the page showing the deep zoom block in your browser to see the changes. [[https://openseadragon.github.io/|OpenSeadragon]] is what powers the deep zoom, in case you want to learn more about this technology.+If you have access to the file system of your Blocks server (e.g., you're running Blocks locally on your laptop), you can locate these files under public/block/<group-name>/deepzoommap/custom/index.html, in case you want to try any [[https://openseadragon.github.io/docs/|other options]]. Just open the //index.html// file with a plain text editor and hack away. Reload the page showing the deep zoom block in your browser to see the changes. [[https://openseadragon.github.io/|OpenSeadragon]] is the open source project that powers this deep zoom function.
  
  
 ====Preparing high resolution images for deep zoom==== ====Preparing high resolution images for deep zoom====
  
-A Java-based program is used to preprocess any images to be used for deep zoom. In order to use it, you must have a recent version of Java installed on your computer. If you're not sure, do as follows:+A Java-based program is used to preprocess for deep zoom use. This program requires a recent version of Java installed on your computer. If you're not sure if this is available, do as follows:
  
   * Open a terminal window.   * Open a terminal window.
   * Type //java -version// and press enter.   * Type //java -version// and press enter.
  
-If this command isn't recognized, you need to [[https://adoptopenjdk.net|download and install]] Java before proceeding. If a version number is shown, make sure it's version 8 or later.+If this command isn't recognized, you need to [[https://adoptopenjdk.net|download and install]] Java before proceeding. If a version number is shown, make sure it's version 8 or later. You should also make sure the JAVA_HOME enviroment variable is set on the computer (at least on windows). If it is not you cannot just type java in the terminal, you will have to use the full path to java everytime you use it.  Use google to see how to do that.  
  
-Then go ahead and {{:blocks:app-note:deep-zoom:pyramiddzitool.zip|download}} the program used to process high resolution images. This free command line program is in the public domain, kindly provided by the National Institute of Standards and Technology. More details can be found [[https://github.com/usnistgov/pyramidio|here]].+Then go ahead and {{:blocks:app-note:deep-zoom:pyramiddzitool.zip|download this program}}. This is an open source (public domain) command line program, kindly provided by the National Institute of Standards and Technology. More details can be found [[https://github.com/usnistgov/pyramidio|here]].
  
-Extract the //pyramiddzitool.zip// file. Inside, you'll find a high resolution example file. The tool support both JPEG and PNG source files with 8-bit-per-component RGB data. If you run into trouble processing an image of your own, you may need to open and re-save the image as such using an image editing program, such as Photoshop or Gimp. +Extract the //pyramiddzitool.zip// file. Inside, you'll find a high resolution example file. The tool supports JPEG and PNG image files containing 8-bit-per-component RGB data. If you run into trouble processing an image of your own, you may need to open, convery and re-save the image using an image editing program such as Photoshop or Gimp. 
  
-We've included two script files showing how to use the command line program; //process.bat// for Windows and //process.sh// for MacOS and Linux.  These scripts are just one-liners containing the command for processing the example //hr.jpg// file, generating the pyramid image data in the //out// folder. Run the script from a command line window, after navigating to its location, to start the process. You may also copy the content of the script file and run it as is in the terminal. This is what's inside the script files:+Two script files are included, showing how to use the command line program; //process.bat// for Windows and //process.sh// for MacOS and Linux.  These scripts are just one-liners containing the command for processing the example //hr.jpg// file, generating the pyramid image data in the //out// folder. Run the script from a command line window, after navigating to its location, to start the process. Alternatively, copy the content of the script file and run it as is in the terminal. This is what's inside the scripts:
  
 <code> java -Xms1G -jar pyramidio-cli.jar --tileSize 510 -i hr.jpg -o out</code> <code> java -Xms1G -jar pyramidio-cli.jar --tileSize 510 -i hr.jpg -o out</code>
  
-To process another source file just copy the file to the same directory as the tool and change //hr.jpg// in the command to the name of your new file. The result will end up in the //out// directory prefixed with the source image file name. Avoid using spaces or non-ASCII characters in the file name. +Be patient, it takes a minute or so. You will se this message in the terminal while the process is running: 
 +<code> INFO: Making directory archiver for out </code> 
 +To process another image, just copy the file to the same directory as the tool and change //hr.jpg// in the command to the name of your new file. The result will end up in the //out// directory, prefixed with the source image file name. Avoid using spaces or non-ASCII characters in the file name. 
  
 Copy the resulting file and folder from inside the //out// directory into your deep zoom block's //custom/out// directory. Copy the resulting file and folder from inside the //out// directory into your deep zoom block's //custom/out// directory.
Line 106: Line 111:
 ====Using multiple deep zoom images==== ====Using multiple deep zoom images====
  
-This [[https://int.pixilab.se/outgoing/permanent/wiki/DeepZoom.zip|example block]] uses a slightly modified version of the //index.html// file accepting [[https://en.wikipedia.org/wiki/Query_string|query parameters]] controlling the tileSource option in the script. The block structure used here is as follows:+The next [[https://int.pixilab.se/outgoing/permanent/wiki/DeepZoom.zip|example block]] uses a slightly modified version of the //index.html// file accepting [[https://en.wikipedia.org/wiki/Query_string|query parameters]] controlling the tileSource option in the script. The block structure used here is as follows:
  
   * A Composition at the top-level.    * A Composition at the top-level. 
   * A number of smaller Compositions for building a simple menu.    * A number of smaller Compositions for building a simple menu. 
-  * A Book for loading the web pages selected on the menu.+  * A Book for showing the image selected on the menu.
    
-The menu buttons each have two actions; one setting a Spot Parameter subsequently used to control the tileSource, the other locating page2 in the Book, exposing a Web Block showing the deep zoom content.+The menu buttons each have two actions; one setting a Spot Parameter subsequently used to control the //tileSource//, the other locating //page2// in the Book, exposing a Web Block showing the deep zoom content.
 The close button returns to the menu.   The close button returns to the menu.  
  
 {{:blocks:app-note:deep-zoom:multisourceblock.jpg?800|}} {{:blocks:app-note:deep-zoom:multisourceblock.jpg?800|}}
  
-The Web Block uses feature allowing you to pass Spot Parameters to a custom web page as query parameters. Here we pass the //tileSource// parameter set by the buttons. Multiple parameters can be passed, if desired, by listing their names, comma separated.+The Web Block uses feature allowing you to pass Spot Parameters to a custom web page as query parameters. Here we pass the //tileSource// parameter set by the buttons. Multiple Spot Parameters can be passed along by listing their names, comma separated.
  
 {{:blocks:app-note:deep-zoom:webblockconfig.jpg?800|}} {{:blocks:app-note:deep-zoom:webblockconfig.jpg?800|}}
Line 124: Line 129:
 ===Using query parameters from custom HTML content=== ===Using query parameters from custom HTML content===
  
-Below you can see an example of how to use query parameters from within custom HTML code. This is similar to the example shown earlier, but adds some code to extract and access query parameters, setting a number of deep zoom options. Additional options can easily be added as query parameters, as needed.+Below you can see how you can use query parameters from within custom HTML code. This is similar to the example shown earlier, but adds some code to extract and use query parameters, here for setting a number of deep zoom options. Additional options can be added as query parameters, as needed.
  
 <code> <code>