Better understanding of Custom Tilesource

Hello, So I’m having difficulties understanding a custom Tilesoruce. Let’s look at their example code for a second from (https://openseadragon.github.io/examples/tilesource-custom/) Ie.,

OpenSeadragon({
    id:            "example-custom-tilesource",
    prefixUrl:     "/openseadragon/images/",
    navigatorSizeRatio: 0.25,
    wrapHorizontal:     true,
    tileSources:   {
        height: 512*256,
        width:  512*256,
        tileSize: 256,
        minLevel: 8,
        getTileUrl: function( level, x, y ){
            return "http://s3.amazonaws.com/com.modestmaps.bluemarble/" +
                    (level-8) + "-r" + y + "-c" + x + ".jpg";
        }
    }
});

What am I confused about: For my questions let’s set OpenSeadragon viewport to a static size 1920 x 1080. Questions:

1. What is prefixUrl do? Is this where the OpenSeaDragon source code is stored?
2. How do you know how many tiles are going to be requested? I don’t understand there equations for number of tiles.
3. Is there any way to have a dynamic number of tiles with respect to level? If I’m viewing a scaled down version of a huge image, sending a 1920x1080 image as one tile isn’t that slow.
4. How does the above code know what level of magnification I want to view ( i.e., how does the above code know I want to see the entire image in the viewport?
5. Assuming I’m understand how the number of tiles are calculated (which I don’t), how does the above code loop through the requested tiles? For example if your at level 1, and you have 4 tiles, it will asked for: http://s3.amazonaws.com/com.modestmaps.bluemarble/1-r0-c0.jpg http://s3.amazonaws.com/com.modestmaps.bluemarble/1-r0-c1.jpg http://s3.amazonaws.com/com.modestmaps.bluemarble/1-r1-c0.jpg http://s3.amazonaws.com/com.modestmaps.bluemarble/1-r1-c1.jpg

correct?

1. Reading through some of the forums here, it seems like a lot of you really understand the Custom Tilesource. Where was all this documented, the link above just gives you the example code but doesn’t really explain how the custom tilesoruce works (neiter does the API docs).
2. Is there some assumption that level one will fit the image to the view port?
3. Does the custom tile support request for the next user move ( what I mean by this is, if you load the image and it needs all the level 1 tiles to display the image, does it request all the level 2 images as well, so when the user zooms in those tiles are already in the cache? Additionally, if a user is already zoomed in does it request tiles outside the viewport so when the users pans around, they don’t have to wait for the panned tiles to load? Thanks everyone for all the help! I’m sorry if a lot of these were already answered. If they were just paste the link . Best wishes!

[iangilman]

Wow! Lots of questions. Sounds like you may need to get to know OpenSeadragon with regular tile sources a little bit before getting into custom tile sources, just so you have a grounding in the basics. Anyway, I’ll try to answer.

1. What is prefixUrl do? Is this where the OpenSeaDragon source code is stored?

That’s a link to the images OpenSeadragon uses in its UI (the buttons at the top). It’s likely next to the OpenSeadragon library file you’re using.

1. How do you know how many tiles are going to be requested? I don’t understand there equations for number of tiles.

There are actually other types of custom tile sources that you can create by subclassing TileSource, but the sort shown in the example is the easiest to use. It assumes a DZI-style pyramid, where each level is twice the dimensions of the level before it (e.g. level 0 is 1x1px, level 1 is 2x2px, level 2 is 4x4px, etc.). If a level is bigger than your tile size, then it’s broken up into tiles that match the tile size (e.g. a level that is 512x512 would be made of 4 tiles if the tile size is 256). The top level is the width and height that you specify in the tile source.

1. Is there any way to have a dynamic number of tiles with respect to level? If I’m viewing a scaled down version of a huge image, sending a 1920x1080 image as one tile isn’t that slow.

With this kind of custom tile source, you can only specify a single tile size, and it has to be square, but you can certainly specify 1920 or whatever for your tile size. It’s generally considered best practice to use powers of 2, so 1024 or 2048 would be good choices. Any level that’s smaller than your tile size will be whatever that level size is, not padded out to fit the tile size.

1. How does the above code know what level of magnification I want to view ( i.e., how does the above code know I want to see the entire image in the viewport?

This has nothing to do with custom tile sources; it’s just OpenSeadragon’s viewport behavior. By default you always start out with the image zoomed to fit the viewer you give it. Then of course the user can zoom and pan as they want.

1. Assuming I’m understand how the number of tiles are calculated (which I don’t), how does the above code loop through the requested tiles?

Actually this custom tile source example is a little confusing, since it’s such a giant data set (satellite imagery of the Earth). Also note that the min level is 8, and then the URL subtracts 8 from the level. Anyway, you’ve got the basic idea.

1. Reading through some of the forums here, it seems like a lot of you really understand the Custom Tilesource. Where was all this documented, the link above just gives you the example code but doesn’t really explain how the custom tilesoruce works (neiter does the API docs).

Indeed… the documentation could probably be improved. Perhaps you can help with that as you get a better understanding of how things are put together. At any rate, thank you for drawing attention to the issue.

1. Is there some assumption that level one will fit the image to the view port?

There’s really no relationship between tiles and what goes where in the viewport. Or rather, that’s all under the hood and has nothing to do with the tile source. At any rate, as mentioned before, level 0 is generally 1x1 pixel and level 1 is twice as big as that.

Here’s more info about the DZI format (which basically describes the kind of pyramid the custom tile source you’re looking at is expecting):

https://msdn.microsoft.com/en-us/library/cc645077(VS.95).aspx

1. Does the custom tile support request for the next user move ( what I mean by this is, if you load the image and it needs all the level 1 tiles to display the image, does it request all the level 2 images as well, so when the user zooms in those tiles are already in the cache? Additionally, if a user is already zoomed in does it request tiles outside the viewport so when the users pans around, they don’t have to wait for the panned tiles to load?

OpenSeadragon doesn’t do any predictive loading. We’ve found that loading as you go is actually plenty fast. At any rate, even if we did do predictive loading, it would have nothing to do with the custom tile source. Tile sources just specify how to map from levels and tiles to image URLs.

Now that I’ve answered your questions, why are you interested in custom tile sources? Do you already have a data set you want to support? If not, have you looked at the standard tile sources and found none of them serve your needs?

[iangilman]

Yes, all of the documentation goes through pull request. And yes, feel free to close this issue 😃