The Locations button in the main toolbar appears whenever an open map or similar window has the focus.  The Locations button has three functions:





The Locations button also works for layouts when a frame that shows contents from a map, drawing, image, or labels component is enabled for panning and zooming by being double-clicked.  

About Locations

 Locations save a particular geographic location with an associated scale, thus saving a given view in a map or other window to which we can return.  Locations are simply text components that contain a geographic center written in latitude / longitude decimal degrees using WGS84 datum, and a scale.   Locations can optionally specify an Entity, the name the location should launch if no window is open when we command a view of that location.


To view a location, right-click on that location in the Project pane and choose View or View in Active Window.  Any window can use a location, not just the window from which the location was created, and not just a window for the location's default entity if an entity is specified.   


Double-clicking a location in the project pane opens the location so we can see and edit the JSON text within it that specifies a geographic center and scale.  We can edit that text to change, for example, the scale saved in a location.   Changing the scale saved in a location will change the zoom level of the window when that location is used.  


The scale is absolute, just like the scale readout in the status bar: it shows true scale for the center of the view in whatever coordinate system is used by the window.  For example, if the scale is 3000 that means 1 centimeter on the screen corresponds to 30 meters, regardless if the window uses Pseudo-Mercator, Latitude / Longitude, or some other projection.


Download the project used in this example from the Cathedrals.mxb link in the Examples page on the Manifold website.    See the Example: Locations topic for a step-by-step tutorial on using Locations.


Save a Location using a window:


  1. Pan and zoom to the view desired.

  2. In the Locations button menu choose Save Current Location.

  3. A new Location appears in the Project pane.  Rename it as desired.

  4. The new Location will be created with an Entity entry naming the default component.




Create a new Location for an Open Window


  1. Open the desired window.
  2. Pan and zoom to the desired view.
  3. Choose File - Create - New Location
  4. Enter the Name.  The Based on, Longitude, Latitude and Scale will be taken automatically from the active window.
  5. Press Create Location.
  6. The new Location will be created with an Entity entry naming the default component, as it appears in the Based on box.



In the above, if desired we could enter whatever latitude, longitude and scale values we desire instead of using those the dialog offers by default.  For example, suppose we prefer using a round number for a scale, such as 3000, instead of a number such as 3153.03349034.




Sometimes we would like to copy and paste latitude and longitude coordinates to create a location.   For example, suppose we have launched a web site that gives the latitude and longitude coordinates for a point of interest.  If they are in decimal degrees format we can copy the latitude and longitude from the web site and paste them into the New Location dialog.


Create a new Location using Coordinates


  1. Right-click into the project pane.
  2. Choose Create - New Location
  3. Enter the Name.  
  4. Choose <new location> in the Based on dropdown menu.  
  5. Enter the desired Longitude, Latitude and Scale.
  6. Press Create Location.


The above method creates a location that does not have an Entity entry.    


If we would like to create a location with an Entity entry, we would start by right-clicking on the desired component in the Project pane, and then proceeding with Create - New Location and so on.  The component we right-clicked will be automatically used as the Entity for the location.


Go to a Location in a window:


  1. Open the desired window.
  2. In the Locations menu choose the desired Location.
  3. The window will pan and zoom to the chosen Location.




Go to a Location in a window:


  1. Open the desired window.
  2. Right-click onto the desired Location in the Project pane.
  3. In the context menu, choose View in Active Window.
  4. The window will pan and zoom to the chosen Location.




If a location has an Entity entry referring to a component such as a map or drawing, the View command in the context menu will automatically open that component if it is closed.


Go to a Location with an Entity entry:


  1. Open the desired window.
  2. Right-click onto the desired Location in the Project pane.
  3. In the context menu, choose View.
  4. The referenced component will automatically open.
  5. The window will pan and zoom to the chosen Location.



 Locations are components in the Project pane just like comments, tables, drawings or maps.  They can be copied and pasted, and, just like comments, they are plain text that can be opened and edited.  The plain text is in JSON form so Locations are easy to create or modify using SQL or scripts.


To fit into this documentation, illustrations show a small Manifold desktop, with only a few panes, docked to the right side.   In real life we use a much larger Manifold desktop, and all panes would be turned on, with panes docked to the left or to the right. Some users working with large monitors prefer to organize their panes so that some are docked to the left and some to the right, or with some panes docked above or below others.  


Right-click a pane's  tab to change where it is docked.  Manifold will remember that new arrangement for our next session.





The project above has six locations components, all of which are in the Locations folder.



We can double-click open the Rouen Cathedral location to see it is plain text, organized using JSON notation, that gives the center of the view and the scale for the view.   We can edit the text of the location if we like.  For example, we could change the 3000 for the Scale to 5000 and then after we close the edited location, using it would zoom to a scale of 5000 instead of zooming to a scale of 3000.  


The Entity entry is optional.  If it exists in the Location and names a component that is in the project, the context menu on that location in the Project pane will have a View command that is enabled.  Choosing View will automatically open the component named in the Entity if it is not yet open, and then pan and zoom to the location.   This is a convenient way of specifying a default component to use with a Location in case the user forgets to first open a window before trying to use the Location.

Descriptions for Locations

When a location is open in its own window, as seen above, and has the focus we can open the Info pane and enter a Description for that location by clicking the [...] browse button for the Description.   Descriptions can be handy for more information to describe the location than just the name of the location.  Descriptions will also appear for locations when a component is served to the web using Manifold Server.

Example: Save Current Location



We have a project with a map that shows two Bing layers, a streets layer and a satellite imagery layer.  The map is opened and has been panned and zoomed to show France.   The project also has a Locations folder in which we have placed the various locations we have created, to avoid cluttering up the root of the project with lists of locations.  There is nothing special about that name.   We have simply chosen the name "Locations" for the folder because that tells us what it is, and it is less confusing than naming the folder "Harold".  


We have clicked the Locations folder to highlight it, so it has the focus.





 We click on the Locations button and in the drop-down menu we choose Save Current Location.  





A new location, named Location by default, is created within the Locations folder that was highlighted.   The folder automatically opens to show the contents.


  Whenever we work with an active, open window the context for what we do is the data source from which that window was opened.  Saving the current location for the active window saves it within whatever is the context data source, within whatever folder in that data source has the focus.    The context data source has to be writable, so we can save a location to it.  


The Map above was opened from the local project, so the local project is the context data source, and the local project is where any locations saved for that Map will be created.





We slow-double-click the new location to change the name to something more memorable.   We will enter All France as the new name and press Enter.





The newly named location automatically is resorted to the top of the list of items within the Locations folder.

Example: Go to a Location

We will go to one of the locations we have previously created in this project.  We will take a look at a cathedral in the champagne wine region.





 We click on the Locations button and in the drop-down menu we choose one of the existing locations, Reims Cathedral.  The drop-down menu lists all of the locations that exist in the project.





Instantly, the map window pans and zooms to that location.   Microsoft's Bing is not that interesting, as it does not show the footprint of the cathedral as it once did, so we will drag and drop an OSM (OpenStreet Map) images server layer into the map:





OSM is  more informative, since by default it shows building footprints in the base street map.





Double-clicking the upper, streets layers tabs to turn them off we can see in the Bing satellite layer below an overhead view of cathedral in Reims.  The plaza in front of the cathedral has champagne boutiques and cafes and restaurants, such as the Au Bureau brasserie with outdoor dining seen in the lower left of the image above.   Visit Au Bureau and sip fine champagne while enjoying lunch  with a view of the cathedral.


Map layers pan and zoom together, but even if the image layer were opened in its own component the location would still work for it.   Locations work to pan and zoom whatever component has the focus, whether it is an image, drawing or labels component or layer.

Go to a Location using the Context Menu

We can also go to a location by right-clicking it in the Project pane and choosing View in Active Window.





For example, if we want to go to the Chartres Cathedral location we right-click onto Chartres Cathedral and then we choose View in Active Window.





The view immediately pans to Chartres.  The bright white umbrellas in the lower center, on the corner of the building nearer to the cathedral, mark the outdoor dining terrace of Le Serpente, Manifold's favorite restaurant in Chartres.  For a street view of Le Serpente, see the Example: Connect to an OSM Vector Server topic.





 We can go back to the view of all of France by choosing the All France location in the drop-down menu.  





Right away, the map pans to that location.  Locations are not tied to any specific component or layer.  They are simply geographic locations and scales that can apply to any visual window that has a coordinate system that makes sense in a geographic setting.



We double-click the streets layer tab to turn that layer back on, to show that we have indeed returned to the location previously saved.

A Nuance

Whenever we open an active window directly from within an external data source, that data source becomes the context for what we do.  It is as if we have teleported into that data source.   That is one way Manifold helps us keep our bearings in a situation where projects can link in hundreds of external data sources, and where each of those in turn could link in yet hundreds more of nested data sources.    


When we open an active window from within an external data source, any locations we wish to save will be saved within that external data source, if it is writable, and the list of locations shown by the Locations button will be a list of locations found within that external data source.





Suppose, instead of opening a map within our project, we click open the OpenStreet Maps Base data source hierarchy and, from within that hierarchy, we double-click open the OpenStreet Maps Base Image.    Manifold is happy to open that image for us, so we can look at it and pan and zoom within it as if it were local within our project, and not being automatically linked into our project from the external servers that host OSM streets data.





However, if we click on the Locations button we will see no list of locations and no ability to save the current location.  We cannot save the current location because the OSM data source is read-only in terms of creating new components: the OSM data is coming to us from web servers maintained by the OpenStreetMap organization and they do not allow us to write data into their servers.   We see no list of locations because the OpenStreet Maps Base web server does not contain any Manifold locations.   If it was a data source that was some Manifold project that contained locations, we would see those, but OSM is just a web server that serves tiles.  


The Locations button does not show any list of locations from within our local project, because the context for the active, open Map is the OpenStreet Maps Base web server data source.




If we want to pan and zoom the OSM image window to one of the locations in our project, that is easy to do.  We right-click on the location desired and we choose View in Active Window.   In the illustration above we have done that for the Amiens Cathedral location.





Right away the window pans and zooms to the Amiens Cathedral location.  


Note that the OSM base map reports the name of the cathedral, Notre Dame, since many of the great cathedrals in France are named for "Our Lady," Notre Dame, the same name used for the famous cathedral in Paris.  

Example: Go to Another Window's Location

Suppose Window A is open and shows a particular view and Window B is open and shows a different view.     We would like to pan and zoom Window A to the location shown in Window B.  With Window A open and window B open, we choose View - Locations - Windows - Window B and Window A will instantly pan and zoom to the same view currently shown in Window B.





Suppose we have opened the Bing streets image in its own window, as seen above.   We have panned and zoomed the Bing streets image window to a view of central Rome.  The illustration above shows the focus is on the Map window that shows France.





 When another window is open, the drop-down menu for the Locations button will include a Windows entry at the top, which leads to sub-menu listing all opened windows, even those with very long names.  We choose the Bing streets image window.





Right away, the map window pans and zooms to the same location that is seen in the Bing streets image window.

Example: Windows are Independent

When it comes to locations, windows are independent.  We can open the same component in two different windows at the same time and apply locations to both of the windows separately, or to use the view in one of those windows to guide the other window.





In the illustration above, with the focus on the Map we have chosen Windows - New Window to open that same map in a second window, named Map (2) by default.   The new window opens by default with a zoomed to fit view showing the entire world.





 With the focus on the new Map (2) window, we choose one of the existing locations, Chartres Cathedral.  





As expected, the Map (2) window pans and zooms to that location, showing the unhelpful Bing streets display for the location of Chartres cathedral.  Even though the Map (2) window is a window into exactly the same component as the Map window, it may be panned and zoomed independently.


To pan and zoom the Map window, we click on the name tab for the Map window to move the focus to that window.





 Since the Map (2) window is open, the drop-down menu for the Locations button includes a Windows entry at the top, which leads to sub-menu that lists the Map (2) window.   We choose the Map (2) entry.





The window with the focus, the Map window, immediately pans and zooms to the same location that is shown in the Map (2) window.   That both of the windows are panning and zooming into the same component does not matter, since each window can have an independent view.


One way to maintain a visual list of locations of interest is to open the area of interest in one big window and to then also open that same component in several smaller windows, each of which is panned and zoomed to a location of interest.  We can then use the locations Windows sub-menu to instantly jump the main window to any of the locations shown in smaller windows.    That works even if those other windows use completely different components, such as an OSM image layer or some drawing.

Example: Any Window can be a Guide

Any window can be a guide for any other window.





With the focus on the Map window, we press the Back button in the main toolbar to go back one view.





The Map window now shows the previous view of Rome, while the Map (2) window continues to show the view of Chartres cathedral.    We have clicked on the Map (2) window to move the focus to that window, so the Map (2) window is now the active window.





 The Locations button now lists options from the context of the Map (2) window being the active window.   Since the Map window also is open, the drop-down menu for the Locations button includes a Windows entry at the top, which leads to sub-menu that lists the Map window.   We choose the Map entry to go to the location shown by the Map window.





Right away, the Map (2) window pans and zooms to the same view shown by the Map window.


See the Example: Locations topic for another example of the above.

Where Locations are Saved

When working with an active window, if we choose Save Current Location the new Location will be created within whatever data source hosts the active window.  That data source must be writable, so a new Location component can be created.    If the focus within the data source is on a folder, the location will be created within that folder.


If we link a project called France as a data source into our project and then we open a map called Regions from within that France data source, any locations we create while working with that Regions map will be created within that France data source, not within the local project.   Likewise, when we are panning and zooming within that Regions map, if we click on the Locations button it will show us a list of any locations within the France data source, not within the local project.


In the illustration below, the project has three external data sources linked into the project:  it has connections to the Bing Maps Satellite server, to the Bing Maps Street Map server, and to the OpenStreet Maps Base server.    


The local project is also a data source, the .map file the project uses.  Everything in the local project section of the project pane is stored locally in the .map file.  Everything in the web servers section is stored externally, in web servers outside of Manifold, with the data streamed into the project as required.





A web server data source is read-only for creating components.  In contrast, we can do whatever we like in a local project, provided that we have not deliberately opened the .map project file in read-only mode.





In the illustration above, we have opened the OpenStreet Maps Base Image, and we have panned and zoomed the window into a view of Monte Carlo.   If we press the Locations button we see that the Save Current Location command is disabled.    It is disabled because the window with the focus comes from a web server data source that does not allow the creation of new components, like locations.





In contrast, consider the case where we have created a map in the local part of the project and then we have dragged and dropped the OpenStreet Maps layer into it.





We can now Save Current Location, because the Map we created lives in the local project.   





The new location appears in the local part of the project.

Locations that Automatically Launch Windows

We can create Locations that will automatically open the desired component in a window.  This is convenient when publishing projects that contain lists of Locations for use by inexpert users, who might forget to first open a window before wanting to view a particular Location.  



Any location which includes an Entity entry in the JSON text, as seen above, will enable a View choice in the context menu.   The Entity entry:


"Entity": "[Map]",


... tells the Location to use a component called Map, if that is available.


Choosing View in the context menu will open the named entity, a component called Map in the illustration above, and then pan and zoom the view to the location.   If no such component exists in the map, the View command does nothing and the View in Active Window context menu command can be used in the usual way.





Creating a location with an Entity entry is the default.   With window called Map open, showing a map of Paris zoomed into the Pont Neuf, a bridge across the Seine river, we right-click into the project pane and choose Create - New Location.



We enter Pont Neuf for the Name and press Create Location.   That creates a new location called Pont Neuf.


Note: The illustration above shows shortened values in the Longitude and Latitude boxes.  Manifold will open the dialog with full precision using seven more digits past the decimal point than the numbers shown above.  We can use the longer numbers for greater precision, but if we prefer, we can shorten the numbers or enter whatever longitude and latitude numbers we want to use for the location.



We can double-click open the new Location to see the JSON text it contains:


{ "Center": [ 2.341265229, 48.85712427 ], "Entity": "[Map]", "Scale": 10000 }


If we change our minds about having an Entity in the Location, we can simply delete it from the text:


{ "Center": [ 2.341265229, 48.85712427 ], "Scale": 10000 }


However, for this example we will leave the Entity in the JSON text in the Location.





Suppose the Map is now closed.   We can right-click onto the new Pont Neuf location.


Choose View in the context menu.





The system automatically opens the component named by the Entity and pans it and zooms it to the location specified.  

Local Locations for External, Read-only Data Sources

Creating locations within the context data source makes it easy to keep locations associated with the maps, images and drawings for which they were created.    If we open a map in an external data source and we mark locations based on what we see, we generally want those locations to be available when that map file is opened again, whether we open that map file again in the current project or whether it is linked into some other project.


Consider a Manifold project with a map that shows all of our company's factories worldwide.   That project may be saved on our company's servers as an archival .map project that can be linked into many different other projects.   If we link it into our local project and open the map, panning and zooming for views of various factories, the usual objective when we save Locations to get back to those factory views is that we want those Locations available for use not just in our current project but available for use in any other project that links in that archival .map project.    Saving the Locations in to that same, archival .map project ensures the locations will travel with that .map into whatever project that links that .map.





For example, in the illustration above we have opened a local project called Europe, a project similar to that illustrated in the Example: Create a Data Source within an Existing Data Source topic.   The Europe project links in data servers from three other .map projects, including a project called England, a project called France and a project called Germany.    We have drilled into the France project, where we see it contains a Facilities Map, which we have opened, that has a layer showing our company's factories in France.


This simulates a situation where a company has archival projects stored on some central server that various departments around the world might use.   In this case, if we create Locations that show close-up views of our factories, we would like those Locations to be created within the France project.  





For example, if someone wants to see the Orleans location they can choose it in the Locations button.





That will pan and zoom our map view to exactly that location.


Sometimes, however, we want to save Locations locally even if they are based on an external data sources.   That may be because the external data source is read-only, like the OSM server in the illustrations above, or because we do not want to modify the external data source by adding our Locations to it.   That is easy to do.





Suppose, for example, we have double-clicked open the OpenStreet Maps Base Image directly from within the data source.   We haven't added it as a layer to a map, we've just quickly opened it, and then we have proceeded to pan and zoom to find exactly the right location of interest.   Now, we would like to save that location so we do not have to do all of that work again to find it.  But when we go to save the current location the command is disabled, because the context data source is a read-only web server.   Ouch.  


No problem, and no need to panic.   Without closing the existing window we create a new Map.    In this example, we'll use the new Map we created earlier.





We open the new Map, which has one layer, the OpenStreet Maps Base Image layer we dragged and dropped into the Map.    That layer is coming from an external web server, but it is appearing in a Map for which the context is the local project.





Next, in the Location button's Window command we choose the OpenStreet Maps Base window that is still open.  





That pans and zooms our Map window to exactly the same view that is shown in the window into the web server image.   





The data source context for the Map is our local project, so we can Save Current Location.





The new Location appears in our local project, named Location 2 by default.


Data Sources and Locations - Besides being created and stored in a .map project, a Location can be created and stored within any data source that supports writes to the mfd_meta table Manifold creates within that data source, for example, typically within any DBMS which we have linked read/write into the project.


Migration from Release 8 - Opening .map  files created by Release 8 migrates component views into locations. The created locations are put into the same folder as the producing component.


Locations Exist within their Data Sources -  A flip side of creating Locations within the context data source of the subject window is that the Location button only can use those Locations which are within that data source as well.   If in the example of factory locations above we created a new Location within the France project, say, for the city of Nantes, then only a window that was opened within that France data source would have that Nantes location appear in the list for the Locations button.    If we wanted that location to be available elsewhere within the project, we could simply copy it and paste a copy wherever we wanted within the Project pane hierarchy.


Incompatible Coordinate Systems - Some coordinate systems are limited as to what part of the world they can show.  For example, an Orthographic coordinate system center on the North pole cannot show any locations South of the Equator.   If the coordinate system of the active window cannot show the center of the location, selecting the location does nothing.


Locations can be manipulated - Locations can be manipulated very much like any text component:, for example:



Locations from Queries - To learn how to create a location from an SQL query, choose File - Create - New Location and then press the Edit Query button.





For example, suppose in the illustration above we have a view of a map that shows France.



Launching File - Create - New Location opens the New Location dialog pre-loaded with the Latitude, Longitude and Scale of the current view.   We press the Edit Query button to launch the SQL Command Window loaded with a query that creates the Location.


-- $manifold$


-- Auto-generated

-- New Location



  PROPERTY 'Text' '{ "Center": [ 1.5485272634194371, 46.94755744147237 ], "Entity": "[Map]", "Scale": 20629492.83355046 }'



The query above is very simple, and shows how to create Locations using SQL.




Download the project used in this example from the Cathedrals.mxb link in the Examples page on the Manifold website. 

See Also

Getting Started


User Interface


















Layer Opacity


Project Pane


Example: Create Many Locations from a Drawing - Given a drawing of points, we quickly create a folder with Locations for all of the points, allowing us to quickly pan and zoom to a local view around each point.


Example: Locations - Save Locations and use saved Locations to quickly navigate to desired views in windows.


Example: Create a Table from Locations - Create a table that contains, as records, all of the Locations components in a project.  Each record contains the Name, Latitude, Longitude, and Scale of a location.  We use simple, point-and-click operations using the Select and Transform panes.


Example: VBScript to Create Locations from a Table - Use VBScript to take a table where each record has a name, scale, latitude and longitude and for each record create a Location component in the project.