Example: An Imageserver Tutorial

This topic is a companion and introductory topic to the Example: Spectacular Images and Data from Web Servers topic, a must-see topic that provides a gallery of views available from web based data sources.    See File - Create - New Data Source for instructions on connecting to many different types of web servers, including custom web server connection strings.


In  this topic we show a specific, step by step example of how to use imageservers.   We will show every step, even the small steps.  That requires a long sequence of illustrations to show what is done in a few seconds and a few clicks of the mouse in real life.

Adding an Imageserver Data Source to a Project

We begin with a new, blank project.





We click File - Create - New Data Source.






The Type box in the New Data Source dialog is loaded with a very long list of  file types, databases and other possible data sources, including a number of different web server types.   We choose the Web Server: imageserver type and then from the alphabetic list of imageservers (begins with Bing Maps Hybrid) we will choose the imageserver we want.




We will choose the Bing Maps Street Map imageserver.






We will assign a Name of Bing Streets so when we see this data source in the project pane we have a more descriptive name to tell us what the data source is.




We review our choices and press Create Data Source.   A new data source appears in the project, named Bing Streets.






We click on the + icon to the left of the data source to expand the data source.    As we do, Manifold displays the table of tiles fetched from the data source along with the image created to display the tiles.   






We double-click on the imageserver image to open it.  It initially appears zoomed to fit.






At a zoomed out view that shows the entire world streets are not visible.  We zoom into Europe by right-clicking and dragging to draw a zoom box.






As we zoom further in more and more detail appears.   We have an entire world full of detail down to the smallest streets at our fingertips.  We can zoom into a street corner in Bulgaria or visit Times Square in New York.  We can see the smallest road in Africa or choose a path to walk through Beijing.   


However, for the time being we will switch gears, close the street map image by clicking the X in the corner, and add another imageserver, this one providing satellite photography, to our project.


Creating a Map

In Manifold, a map is a component that shows multiple layers.  Those layers can be different images or different drawings.     We will use a map to show a satellite photography imageserver layer together in the same map as the streets imageserver layer.      


To do that we first need to create a map.   We will first create an empty map and then we will drag and drop layers into it.






We choose File - Create - New Map.   




In the New Map dialog we give the new map the name of Bing Layers since the layers we add to the map will both be imageserver layers from Microsoft's Bing web service.  We do not change the coordinate system since a new, blank map automatically assumes the coordinate system (projection) of the first layer that is dropped into it.   


Press Create Map to create the new map.   In the project we double-click on the new map to open it.   It appears as a blank component since no layers have as yet been added to it.






We add the streets imageserver image to the map by dragging and dropping it into the map.






We click Zoom to Fit for the new layer to appear in the map.  Completely blank maps have no scale chosen so when a new layer is added to them the display needs to adjust for an initial view.






As before we see the streets imageserver image.   But now, instead of seeing it in its own image window we see it opened as a layer in the new map that we created.   


Adding a Second Layer to the Project and to the Map

We will now create another imageserver image and add that as a second layer to the map.  To do that we will Right-click anywhere in blank region of the project and in the resulting context menu we will choose New Data Source.   That is another way to get to the same New Data Source dialog that we originally reached by choosing from the main menu File - Create - New Data Source





In the New Data Source dialog we give our new data source the name of Bing Satellite.  The long list of choices for Type is already set at Web Server: imageserver since that was the last choice we made.   In the type of imageserver we choose Bing Maps Satellite, the Microsoft Bing imageserver web server that provides seamless overhead satellite photograph views of the Earth.     Press Create Data Source to create the new data source.





In the Project pane we open the Bing Satellite data source and then we can add the image to our map by dragging and dropping it into the map.






A new tab for the image appears in the tab strip at the bottom of the map and the image fills in, showing a satellite view of the entire world.






Because the image as a layer is opaque it hides the streets image below it.   We can turn the layer off by double-clicking it so we can see the layer below.


The point of adding a satellite photo layer above a streets layer is so we can use the streets layer to more conveniently navigate to a location of interest.   Most people can't find their way around the world based entirely on satellite photos so using conventional street maps is a much easier way to get around.   


When our view into a map is panned and zoomed that view applies to all of the layers in the map whether they are visible or not.   We can navigate to a particular location using the streets layer and then we can turn on the satellite photo layer to see what we want to see.






To zoom into the map we right-click and drag to create a zoom box.    The map pans and zooms into the rectangle we draw to show a closer view of Europe.






The Bing imageserver automatically adds more detail to the display based on zoom level, so as we zoom further into the view country borders will appear as well as the names of countries and the names and locations of larger cities.


Using right-click and drag we will continue zooming further and further into the view until we see a view of the central part of Rome, where the old forum and the Colosseum are located.






At this point we have zoomed far enough so we can turn on the satellite image layer and zoom further based on what we see in the satellite photography.  We turn on the satellite image layer by double-clicking the tab for that layer.






Cool!  Now we have an aerial view of the old Forum, the Colosseum, the Palatine Hill and, running diagonally at lower left, the Circus Maximus.    We will right-click and drag to zoom further into the view to take a closer look at the Colosseum.






There, we've just zoomed in from orbit to see the Colosseum in Rome, and the above is not even the maximum resolution we can see.  There is even more detail if we zoom closer.   


We can see the full resolution of the tiles the Bing imageserver is sending by choosing View - Zoom to Native.  That will adjust the zoom level so that each pixel in the highest resolution tile available takes up one pixel on our monitors.






Zooming to native resolution show the highest resolution of tiles served by the imageserver at a zoom level where one pixel in the tile is shown on one pixel in the screen.   Depending on the number of pixels per inch on the monitor a native zoom will usually show the sharpest visual display of an image.






In native zoom we can easily make out individual people walking about and standing on the tourist platforms overlooking the exposed under-arena infrastructure of the Colosseum.


By zooming in further we can sometimes see a more informative display than native resolution.






In the illustration above we have zoomed further into the view beyond native zoom resolution.   Each pixel in the highest resolution tile is now shown using multiple pixels on the monitor.   Instead of each pixel being the tiniest possible dot on the monitor, each pixel now appears as a small square.     


The image is not as clear:  it is definitely fuzzier, but it may be easier to understand what we see on the observation platform.  Looking closely and perhaps squinting a bit we can see that the people seen in an overhead view from orbit are casting shadows.  The people are seen from overhead in mostly lighter pixels (understandable, since given the warmth in Rome tourists often wear lighter clothes to stay cooler) while the shadows they cast appear as much darker pixels.


Adding a Drawing and Tracing an Object

We now will create a new, blank drawing in the project.   We will do that using a coordinate system (projection) for the drawing that is the same used by the imageserver layers and thus, by the map.  tech_lars_sm-.png


Tech Tip:  Manifold will re-project components on the fly if they appear as a layer in a map and the coordinate system they use is different than the coordinate system used by the map.  For small components, such as drawings that do not have many objects in them or visible in the view, that process can be so fast it might not even be noticed.   But for larger components even a fast re-projection can cause a noticeable pause or take even longer.   We can avoid such pauses by ensuring all components which appear as layers in a map use the same coordinate system as the map.   If we don't care what coordinate system an image or drawing uses, we may as well use whatever the map uses.






To find out what coordinate system the Bing satellite image uses we first click on the Bing Maps Satellite Image tab in the map to make sure it is the active layer.  





We then choose Edit - Change Projection in the main menu.




We do not intend to change the projection - we are simply using the dialog to see what the current projection is.   We could see the same information in the Info pane if we preferred.   In the dialog we see that Bing uses the EPSG:3857 coordinate system, the classic pseudo-Mercator coordinate system favored by most web servers.  tech_lars_sm-.pngWe click Close to close the dialog.


Tech Tip: There are various ways of specifying coordinate systems when working with spatial data.  Manifold basically supports all of them.  Perhaps the very best way of specifying a coordinate system is to use an EPSG code, because EPSG codes are exact and unambiguous.   Coordinate systems are often specified using both names with parameters plus the equivalent EPSG code.  Whenever we see an EPSG code we should use that as the least effort and highest reliability approach.





Next, we create a new, blank drawing.   We Right-click onto white space in the Project pane.





In the context menu we choose New Drawing.  






The New Drawing dialog opens using the Pseudo Mercator coordinate system by default, exactly what we want.   We press the Create Drawing button to create the new drawing.  In fact, what we do is create a new table plus a new drawing to provide a visual interface to whatever data ends up being in the table.






We add the new drawing to the map by dragging and dropping the new drawing into the map.






New layers in a map are added just to the left, that is just above, whatever was the active layer.   If we added the new tab somewhere other than the left-most position we can click and drag the layer to the left.   


We Click the layer to make it the active layer.





When the drawing layer is active, controls such as Create Area that can be used only when a drawing has the focus will become enabled.   We click Create Area to put the mouse into the mode of creating area objects in drawings.






We click at every position where we want a coordinate placed to define the shape of the area we are creating.   As we click at each location a blue coordinate box appears and the outline of the area shown by a blue line grows.  The blue line will extend from the first coordinate placed to whatever is the current position of the mouse cursor, to show what the area outline will be if we click to put a coordinate at that spot.


We keep clicking until we have marked out the perimeter of the Colosseum with coordinate locations that will define the new area we want to create.






When we have clicked the last coordinate we intend, we can right-click anywhere in the drawing to choose to either commit the edit or to abandon it.   The blue line extending to that right-click location does not matter as only the last coordinate marked will count should we choose to commit the edit.






So far, the clicking of coordinates and resulting blue outline has just been a preview.   To commit the changes and create the area we click on Save Changes.   If we change our minds we can abandon the edits by clicking Undo Changes.






The result is a new area object created in the drawing.   We have created this area by, in effect, tracing over what we saw in the photographic satellite image layer below.   


Digital maps, that is drawings, are often created by tracing over aerial photography.  Manifold makes that especially easy by automatically maintaining geographic synchronization between layers in a map and by providing a seemingly endless range of imageservers and other web-based overhead image sources that we can use to get imagery for virtually any location on Earth.


Digitizing many structures, such as all of the buildings in a large city like Rome, will take just one person a long time.    But it still is amazing how fast digitization can go.   In a small to mid-sized town one person can usually easily mark the locations of all, say, fire hydrants in a particular town in only one day.   


In remote areas where digital maps showing dirt roads or trails may be poor quality it is usually very easy to create lines that trace over paths that are visible in imageserver photography.  Such drawings of lines then become the basis of digital maps for the region.



Be careful using cache - When we created new data sources for our imageserver images we checked the Cache data box in the New Data Source dialog.




Creating an imageserver data source with the Cache data option checked will cache all tiles received from the server.   Checking the Save cached data between sessions box will save those tiles within the Project's System Data hierarchy.  That can grow the .map file to very large sizes when it is saved.


Web connections are often fast in many parts of the world but even so fetching tiles from an imageserver is not as fast as fetching them from local storage on local disk.   By caching tiles that we have seen as we pan and zoom within the images served by the imageserver we can provide faster performance, very much faster in the case of slower Internet connections, if we view a scene more than once.   


For example, if we view a scene and then zoom in to part of it, zoom back out and then zoom into another part of it, when we zoom back to views we have already seen if the tiles for that view are cached the system does not need to fetch them from the imageserver over the web but instead it can fetch them much more quickly from cached storage.   If we save the project and then open it later, the cached tiles will still be in the project so any views, such as a zoom to fit followed by zooms into areas of interest, are likely to be viewable using tiles already in cache.


Improved rendering performance by using cache is wonderful, of course, but it comes at the cost of storing tiles within cache tables that are saved within the project.   As we zoom into views and pan to different views the number of tiles we have seen can grow to where the data stored in cache can be hundreds of megabytes.


If we have plenty of free space on disk, terabytes, we might not care about that at all.  But if space is limited or if we want to send a project to someone else without also sending all of the cached tiles we should delete the cache.


Deleting cached tiles - To delete cached data for imageservers we drill down into the System Data hierarchy and then delete the tables storing the tiles.




Click onto the + icon next to the System Data folder to open it.




Within the System Data folder we click open the Cache folder.   We see there are two tables there, one table for the street image tiles served by the Bing streets imageserver and one table for the satellite image tile served by the Bing satellite imageserver.




With the Cache folder highlighted we click the Delete button or simply press the Delete key on the keyboard.




The Cache folder and the two tables it contains are also deleted.   We can delete tables which cache tiles at any time without worries of de-synchronizing what is displayed.  The system adjusts automatically.  



Collections of Web Servers - Check the Product Downloads page for pre-package project files in Release 9 / Viewer .map format that Manifold publishes which contain collections of dozens of popular web servers data sources.


Important:  Some web servers, notably TMS servers, use embedded command tokens.  Use Manifold's custom setting to connect to those.   See the File - Create - New Data Source topic for how to do that.


See Also

File - Create - New Data Source - an absolutely key topic for connecting to many thousands of different web servers.


Web Servers and Image Servers


Example: Spectacular Images and Data from Web Servers - A must see topic providing a gallery of views illustrating how Manifold can use web servers such as imageservers and other free resources to provide a seemingly endless selection of spectacular background maps, satellite images and GIS data with nearly zero effort.


Example: Create a New Data Source from a Manifold Image Server - Manifold image server modules are snippets of code which use the Manifold Image Server Interface (ISI) to automatically fetch image tiles from popular image servers like Virtual Earth, Wikimapia, Yahoo!, Google Maps, Yandex and many others. Image servers can provide street maps, overhead satellite imagery, combinations of streets and satellite imagery and other data as well.  Using Manifold Image Servers is one of the most popular Manifold features.


Example: Create a New Data Source from a MAP File - Create a new data source from an existing Manifold .map project file.   This is the classic way to nest projects, one calling another, to create libraries of data and projects.   Access to nested projects has effectively zero performance loss and the links within projects take up effectively zero space so we can create huge constellations of data at our fingertips.


Example: Create a Data Source within an Existing Data Source - When a data source is writable, for example, if the data source is a Manifold .map file, we can work within that data source as if it were at the top level of our project.   For example, we can create a new data source that is nested within the existing data source.   This example shows how.


Example: Create and Use New Data Source using an MDB Database - This example Illustrates the step-by-step creation of a new data source using an .mdb file database, followed by use of SQL.  Although now deprecated in favor of the more current Access Database Engine formats, .mdb files are ubiquitous in the Microsoft world, one of the more popular file formats in which file databases are encountered.  


Example: Modify GPKG Geometry with SQL then Add Drawing - This topic provides a "Hello, World" example that shows a simple, but typical, task involving spatial data.  We will take a country-sized data set in GeoPackage (GPKG) format and change all areas in the data to the boundary lines for those areas and then save those boundary lines as a new table.  We add a spatial index to the table and create a new drawing to visualize the new table.


Example: Trace an Area in a Map over an Image Background - In a map with a drawing layer above an image layer (served dynamically by an imageserver), create an area object in the drawing by tracing over the outlines of something seen in the image layer below


Example: Style Applied to an Image Server Image - Because the Edit - Style dialog simply changes the way an image is displayed and not the data, it can operate on read-only data served by various web servers such as WMS REST servers.    In this example we look at every detail of creating a data source using a WMS REST  server and then manipulating the appearance of the display with Style.  We will connect to a WMS server that provides LiDAR data in various forms, including as terrain elevation.