mirror/openseadragon
1
0
Fork 0
mirror of https://github.com/openseadragon/openseadragon.git synced 2024-11-24 22:26:10 +03:00
Code Issues Projects Releases Wiki Activity

Updated FAQ (markdown)

Ian Gilman 2023-09-07 14:22:03 -07:00
parent bf0e0c5c12
commit 5b2e1ca034
1 changed files with 14 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
FAQ.md

@ -1,5 +1,6 @@
# Frequently Asked Questions
* [I created an OpenSeadragon viewer. Why don't I see anything?](#size)
* [What do the zoom values mean?](#zoom)
* [Why do I see white borders between tiles?](#tile-borders)
* [OpenSeadragon doesn't work well on mobile devices in portrait orientation](#mobile-portrait)
* [OpenSeadragon isn't working right in my Vue application](#vue)
@ -8,18 +9,31 @@
## Questions and Answers
### <a name='size'></a>I created an OpenSeadragon viewer. Why don't I see anything?
The viewer must be given a non-zero size - both **width** and **height** - in order to see the results. Use your browser's developer tools to inspect the viewer element and see the width and height that are computed. One common problem is not defining the `height` of the viewer. Most of the time, `width` is non-zero by default, because `div` elements are full-width. However, if you have the viewer within a container with `display: grid;` or similar, you may need to define `width` or `min-width` to ensure the viewer can be seen.
### <a name='zoom'></a>What do the zoom values mean?
OpenSeadragon's zoom values are always relative to whatever size fills the width of the viewer. A zoom of 1 means the image width exactly fits the viewer width. A zoom of 2 means the image is twice the width of the viewer. We call this "viewport zoom", and it's particularly well suited to artworks, manuscripts, or anything where you care more about the overall image than the individual pixels. Note that a changes not only when you zoom in and out, but when you resize the viewer.
Another way of thinking about zoom is what we call "image zoom", where 1 means a 1:1 ratio between image pixels and screen pixels, 2 means a 2:1 ratio, etc. This perspective can be important for scientific imaging where you do care about the individual pixels.
You can convert between the two using [imageToViewportZoom](https://openseadragon.github.io/docs/OpenSeadragon.Viewport.html#imageToViewportZoom) and [viewportToImageZoom](https://openseadragon.github.io/docs/OpenSeadragon.Viewport.html#viewportToImageZoom). Note that if you're using [multi-image](https://openseadragon.github.io/examples/multi-image/), you'll need to use the [TiledImage](https://openseadragon.github.io/docs/OpenSeadragon.TiledImage.html) versions of these functions.
### <a name='tile-borders'></a>Why do I see white borders between tiles?
Especially when using images with transparency, you may see seams between tiles. As of release 3.0.1, you can set `subPixelRoundingForTransparency: OpenSeadragon.SUBPIXEL_ROUNDING_OCCURRENCES.ALWAYS` to help address this visual artifact of the tile stitching operation (see https://github.com/openseadragon/openseadragon/discussions/2085#discussioncomment-1957842). Note that this does not fully solve the issue - for example, when the viewer and/or image are rotated, seams may still appear. This is due to intrinsic limitations of `canvas context2d` drawing, and an enhancement to support WebGL drawing is planned.
### <a name="mobile-portrait"></a>OpenSeadragon doesn't work well on mobile devices in portrait orientation
In portrait mode, by default the browser loads a much wider page and then zooms it down, which means the device doing a lot more work than it has to, and it can lead to major delays in loading and navigating an image. This behavior should be fixed by setting `<meta name="viewport" content="width=device-width, initial-scale=1" />` in the `<head>` section of your HTML. (https://github.com/openseadragon/openseadragon/issues/2342#issuecomment-1524071957).
### <a name="vue"></a>OpenSeadragon isn't working right in my Vue application
As of OpenSeadragon release 4.0.0, the technique that `Vue2` uses to observe changes in objects/values interferes with the library. `Vue3` should be used instead. If `Vue2` must be used, to fix this issue, `$.extend` can be replaced by `Object.assign` here: https://github.com/openseadragon/openseadragon/blob/ebab356c207e626b6622f88ffcb0cd28b918f85d/src/viewer.js#L1626
### <a name="tiff"></a>Can I use TIFF files in OpenSeadragon?
OpenSeadragon doesn't support TIFF files directly, but you have a number of options. You could:
* Convert your TIFF file to one of the formats OpenSeadragon supports, like DZI. There are lots of tools for that at https://openseadragon.github.io/examples/creating-zooming-images/.
* Use a server that converts the TIFF file on the fly, like https://iipimage.sourceforge.io/.