- Supported cartography
- Creating Buildings
- Floorplan recommendations
- Uploading floorplans to your building
- Adjusting floorplans to your building layout
- Updating Floorplans
- Erasing floorplans
- Points of Interest
- Wayfinding paths
Supported cartography #
Situm supports 4 cartography formats
Raster images #
Raster images conform the basic cartography supported by Situm. In Situm Dashboard, all floors of the building must have at least one floorplan defined as a raster image. All of them must have exactly the same dimensions (height & width in pixels).
Please take into account:
- We admit PNG, JPEG and JPG images.
- Max resolution is 4096×4096 px.
Please take a look at the Floorplan Section for more information on raster images use and restrictions.
Raster tiles #
If your venue is big, 4096×4096 px might not be enough. One convenient alternative is to use the raster tiles format.
Raster tiles are high-resolution images where, at each zoom level, the image is divided on a set of squared areas or tiles. All tiles have the same resolution (independently of the zoom level), which guarantees a constant real-size / image-resolution ratio on each tile.
You may generate raster tiles with specialized tools such as QGIS and then upload them to Situm (please see our docs for a tutorial on this topic). To that extent, you may package them in a zip file. This zip must one folder per floor to which you want to associate the tiles. Each folder must be named using the ID of each of those floors:
Inside each folder, you will find the typical “zoom/x/y” structure of tile servers:
If you need more resolution, you may try vector maps. In this regard, GeoJSON is a standard open-source format designed to represent geographic information. It supports different types of geometries to present spaces, for example:
- Dots are used to represent points of interest inside a building, such as a cash machine.
- Line chains to represent corridors.
- Polygons to represent rooms.
- … and a long etcetera.
Representing information as geometries instead of as individual pixels has a number of advantages: higher resolution, lighter data weight, etc.
You may upload your GeoJSON directly from Situm Dashboard using json or geojson extension.
Along the same lines, the IMDF (Indoor Mapping Data Format) has been developed in recent years. This specification created by Apple (based on GeoJSON) offers a compact, human-readable, and highly extensible data model for any indoor space allowing the definition of a wide variety of categories of indoor elements, and their characteristics, and attributes.
IMDF offers great benefits over GeoJSON. Mainly, a better support for 3D visualization, look & feel customization, and categorization of indoor elements with semantic labels and properties.
You may upload your IMDF directly from Situm Dashboard using json or geojson extension.
Creating Buildings #
In order to create a building, please click on New building and then click on the map to mark its position. You can also enter your address in the address search box and click on the exact location where you want to place the venue. Enter a name for your building and press Create in order to do it.
Floorplan recommendations #
Image format #
Floorplans should be uploaded in the following image formats: PNG, JPEG, JPG.
The maximum resolution supported is 4096×4096 px. This is because images larger than this can have a negative impact in mobile applications (e.g. take up too much memory or cause long delays while loading).
All the floorplans of a building must have exactly the same dimensions.
It is recommendable to upload an image where the building floorplan fits inside the image layout. The floor plan might be the same size or smaller than the layout but never surpass the layout. Take into account, that the geofences tool and indoor paths must only be drawn inside the canvas.
We recommend keeping the texture of the floorplan as simple as possible to guarantee a good user experience:
- Floorplans should only show spaces and elements that are relevant to the user.
- Space distribution should be presented in a simple manner.
- Soft colours with no gradient or effects are usually preferred.
Uploading floorplans to your building #
To upload floorplans, first select the building where you want to upload them and then click on the “New Floor” button.
The New Floor screen will appear. You may introduce a code name for your floor (e.g. GF for Ground Floor), its order (e.g. 0 for the ground floor, 1 for the 1st level, etc.). You may also set optional parameters such as the altitude of the floor (indicates the level height relative to the ground, only important if you you want to speed up floor changes) and the floor custom fields.
To upload the floor plan, just click on the “Select an image” space and dialog to let you upload a floorplan file will appear. You can search it on your computer and then, press Create. Please take into account the floorplan recommendations.
Once this process is completed, the building floor plan will be shown on the Dashboard in floor list.
At this point, you will have to adjust the building layout to the real building shape (e.g. rotating/scaling the floorplan) as explained in the next section. Finally, you may just click on the “Save” button (floppy disk).
Adjusting floorplans to your building layout #
A very important step after you create your building, is to adjust the layout of your floorplans to the real layout of your building. This means, in essence, placing your floorplans’ coordinates exactly in your building’s coordinates. With this information, we will be able to know important parameters of your building, such as its location, its real size and its orientation. Without these parameters, it is not possible to provide an accurate location estimation.
Main parameters configuration of the layout #
In the following image, you can see the main configuration parameters of the canvas of your building:
- Dimensions (in meters): length and width of the canvas
- Four main corners: top-left, top-right, bottom-right and bottom-left of the canvas
- Rotation angle (in radians): the angle which you rotate your canvas respect to the cardinal axes.
- Building location: the center point of the canvas.
Manual layout matching adjustment #
This is the recommended way since it is easy and yields good results in general. Using this method, you will place one of your floorplans by trying to match the building layout using Google Maps as a baseline. We recommend using the Satellite View for a better building layout visualization.
First, select any of your building levels to adjust its layout. Any changes applied to one level floorplan will be replicated across all the rest of the levels.
Then, you may use the following controls to adjust your building’s layout:
- OPACITY: You can increase or decrease it to find the best fit for the building (1).
- SCALE: Enlarge or decrease the floorplan size by using the buttons located in the corners of the map (2).
- MOVE THE FLOORPLAN: Use the button located in the center of the map to move it (3).
- ROTATE THE MAP: Rotate the floorplan using the curved arrow button (4).
Once the floorplans are adjusted, press the button SAVE, to save the changes. To discard changes press the button X
Corner-based adjustment (advanced users only) #
Another way to adjust your building’s layout is to provide the coordinates of its corners. This method is only recommended to advanced users because the corner coordinates have to be very exact and build a perfect rectangle among them.
You may perform this adjustment by using the control shown in the following image. Note that the corner numbers are properly numbered so you can find them easily.
Center, width and rotation based adjustment (advanced users only) #
The final way to adjust your building’s layout is to provide:
- the coordinates of its center
- its rotation
- its size (width and height)
Updating Floorplans #
In order to update the floor of your building through the Dashboard, you need:
- Select the building you want to update the floor on.
- Click on the pencil icon next to the floor you wish to update.
Once clicked, a form similar to the one used to create a floor will appear, only with the values already set up. In here, you will be able to modify any of the fields, including uploading a new map of the floor or even adding Custom Fields. When all changes are made, you’ll need to click the Update button so the changes are stored in the system.
When updating info on a building, you do not lose any information: you keep the calibrations (should there be any), you keep the ID of floors and building, etc.
Configuring level height #
A floor is an entity representing a certain level of a building. Each floor resource contains, among other information, the physical level of the floor and its floorplan image. All the floorplans of a building occupy the same 2D area in the map, and they should have the same dimensions. As it is shown in the previous picture, the area occupied by a certain floor is defined by the coordinates of each corner of the floorplan, plus the rotation of the floorplan when placed in the map.
Each floor can have a level height, which is the height of the floor with respect to the ground level. For instance, a typical building could have the following configuration:
- Level -2 : level_height = 0m
- Level -1 : level_height = 5 m
- Level 0 : level_height = 10 m
- Level 1 : level_height = 15 m
- Level 2 : level_height = 20 m
- Level 3 : level_height = 25 m
- Level 4 : level_height = 30 m
- Level 5 : level_height = 35 m
- Level 6 : level_height = 40 m
Important aspects to consider when updating a floorplan #
- You will have to maintain the same dimensions if you choose to upload a new floorplan.
- You will have to make sure that the alignment of the floorplan should be the same as the alignment of the rest of the floors in the building.
- If you wish to update a floor on a building with multiple floors, please remember to keep the same dimensions, or else the system won’t let you update.
- If you wish to update a floor on a single-floor building and wish to change the dimensions of the floorplan, please note that it takes a while for the system to update and store the information, which could lead to potential incongruences in the dimensions of the floor. If you are faced with this, you can either:
- contact our support team for help in checking/changing these at firstname.lastname@example.org
- if the building only had test calibrations and no vital information in it, you could also erase the building and create it again with new dimensions.
Erasing floorplans #
In order to erase a floor of your building through the Dashboard, you need to first select the building you want to erase the floor from. Then, click on the trash bin icon next to the floor you wish to erase. Once clicked, you will get a pop-up message, warning you of the consequences of erasing the floor. If you still want to delete, click the ‘Delete’ button and your floor will be deleted.
Please, take into consideration that, if you choose to delete the floor, all calibrations, paths, events and any other types of custom configurations attached to the floor will be permanently deleted. Therefore, erasing or deleting the floor is only recommended in those buildings where calibration has only been done for testing purposes and no definitive configuration/calibration has been performed.
If you have any doubts regarding erasing a floor, please contact our Support Team at email@example.com to make a more informed decision.
Points of Interest #
To create Points of Interest (POIs), go to the POIs option. Select where you want set your POI. To do this, click on the New POI and place the Point of Interest icon on the map.
Then introduce the following information on the “Edit point :
- Name: Type a name for your POI (1).
- Main Category: Choose a category or create new ones (2).
- Subcategories: Adds child categories but which are part of a main category (3).
- Information: Add any information associated with the POI. It can be text, images, links or even videos (4). This information can be displayed by clicking on the POI in your App or in the Mapviewer.
- Custom Fields: Key-value pairs that the user can use to extend and fully customize the information associated with each Point of Interest (5).
Finally, click on Create (6) and the POI will be created. You can create as many POIs as you need.
POI Categories #
You can assign different categories for any POI based on their use. The default categories are shown in the image below.
Each category is represented by a different icon. This icon will appear in the POI both the dashboard and the app. If you have created any categories, they will appear as My categories (1).
Examples of predefined POI categories:
You can also create your own categories by either:
- Clicking on Add a New Category or Subcategories after having clicked on the New POI menu.
- Or by clicking on the Profile icon (1) on the bottom left corner of the page, then going to My Organization (2) and selecting POI Categories (3) from there:
To create a new category you can add:
- Category code: Define a code for your new category.
- Name : Add its name in English.
- Name in Spanish: Add its name in a secondary language (for historical reasons, this was used for Spanish only, but you can use this field to use any secondary language with Situm SDK, Situm REST API and Situm WYF).
- Icon: Upload a default POI icon image.
- Pressed icon: Upload a POI icon image for when the POI is selected.
Finally, click Create to do the new Category.
The Geofencing polygonal areas delimitation facilitates obtaining more complete analytics, and a greater control over the facilities and the work processes, besides deploying more precise geomarketing actions. The geofencing aim is to delimitate areas where is desired to locate a mobile device, it can achieve different goals, some of which are:
- Generate specific analytics from an area;
- Control and record entrance and exit flow;
- Notify activities and tasks to the staff;
- Impact visitors by marketing actions on their devices.
On Situm Dashboard you have the option to delimitate specifics areas of your building.
- Select your building on the Dashboard. Then, on Cartography, you will find the Geofences option (1).
- Select the green button to create a new geofence (2).
- Click to draw (3) the lines that will delimitate the area of your choosing (you can draw different polygonal areas according to the space you desire to select).
- Finally, on the left-side menu choose a name for your geofence (you can also add as much information about this zone as you’d like. Then click on Create (3).
Once created, you can keep making editions on this zone. Click on the nodes in order to expand, reduce or change their shape. Press the center of the area if you want to change its position on the map.
Finally, you can edit the geofence (1) by clicking on it’s name or delete geofences (2) by clicking on the trashcan icon next to its name.
Developers can use custom fields to extend Situm functionality to their own purposes. Some examples:
- Increase the information associated with a resource: Situm is a generic geolocation platform, but you can adapt it to match any information needs. With custom fields, you can put additional information in your resources. For instance, a POI can be converted in a shop with keys such as “brand”, “schedule”, etc.
- Filter information: Custom fields can also be used by the programmer to filter information. For instance, the programmer might set some buildings with a key-value pair similar to “visible”: “true/false”, and then only show in the application those that have the combination “visible”:”true”.
- Link external information: You may also use key-value pairs to associate any resource (building, POI, event) with information stored in another platform. For instance, you may want to associate a shop in a shopping mall with a PDF catalogue of its current coupons. In this case, you may store the catalogue in a server or online storage account, and associate with the POI of the store a key-value pair containing the URL of the catalogue.
- Bind information from Situm to another platform: Another common use case is when you want to associate a resource stored in another platform with a resource in Situm platform (e.g. associate a certain painting stored in a museum’s CMS with a POI in Situm platform). In this case, you may want to create a key-value pair that contains the unique identifier of the resource on the external platform (e.g. in this case, ID of the painting in the museum’s CMS). Then, you will be able to link both resources in your application.
Wayfinding paths #
Paths are a set of nodes and links, where links represent that there is a passable path between two nodes. These paths are used by Situm to compute the shortest route from point A to point B. As shown in the following image, you can create the paths of your building on the Paths section of Situm Dashboard.
Paths can be configured to enable different use cases:
- (1) Accessible / not accessible paths. You can configure path links as not accessible for people with reduced mobility.
- (2) One / Two-way paths. You can indicate that a path is one-way only or two-way. One-way paths are useful, for example, if you want to indicate that users can only go up using a certain escalator but not go down.
- (3) Floor transitions paths. You can link different floors by using elevators, escalators or stairs. You can read a more detailed guide about how to create floor transitions paths here.
- (4) Tags. Tags are custom attributes that can be used to filter the kind of routes that Situm SDK will provide. For example, you might tag one link as “private” and then ask Situm SDK or Situm WYF only to provide the paths that are “private” or to avoid the “private” paths.
Thanks to this, Situm will be able to provide the best route for your user and use case.
Accessible / not accessible paths #
By default, all Situm paths are considered accessible (meaning they can be traversed by people with reduced mobility). Situm also allows tagging them as “Not-accessible”, which allows computing routes that avoid these links, producing accessible routes (e.g. suitable for wheelchair users).
The following figure shows an sample of how to configure the stairs path as “Non-accessible”, therefore a wheelchair user will be suggested to take a different route (e.g. one that uses an elevator). By clicking on the link and unchecking the “Accessible” checkbox, you will configure the link as not accessible (the link will become discontinuous).
One / Two-way paths #
By default, all the links are bidirectional (two-way), meaning that users can traverse them both ways. However, Situm also allows you to define them as “one-way-only”. An example of such a situation would be the security control of an airport or escalators which can only go up or down.
By clicking on the link and changing the “Direction”, you will configure the link as one-way only. The direction of the link will be shown with a directional arrow.
Situm allows associating each link with custom attributes or tags. These can be used to filter the kind of routes that Situm SDK and Situm-based apps will provide. For example, you might tag one link as “private” and then ask Situm to only provide the paths that are “private” or to avoid the “private” paths.
Special Tags #
Situm provides the functionality to designate special tags for incorporating specific instructions during navigation. Presently, Situm features a singular special tag known as ‘sec_control.’ Upon applying this tag, a fresh indication will be generated to highlight the existence of a security checkpoint along the associated route. This new indication can be viewed in the set of instructions that are provided when a route is requested through the Situm Map Viewer. The addition of these tags to different links within the paths can be seamlessly executed through the Situm dashboard. For additional details on adding tags to paths, please consult the following link.
Situm supports the internationalisation of the following cartography elements:
- Buildings: name, address and information
- Floors: name
- Point of Interest (POI): name and information
In order to internationalize these elements, you will need to use custom fields.
- The key will a concatenation between the field name and the translation language (<field name>_<language id>), language specified in following ISO_639-1 convention
- The value will be the translation of the field.
The list of accepted custom fields is shown below
|name_lang -> name
description_lang -> address
info_lang -> information
|name_lang -> name
|name_lang -> name
info_lang -> information
For example, if we want to translate the name of a POI (Point of Interest) into German, the key will be name_de and the value Eingang:
Rest API #
The effect of the previous configuration is to substitute the appropriate fields in the API responses with the right translation. The REST API accepts the header “Accept-Language” and based on its value, translates the appropriate fields. If no translation exists, it falls back to the original field value as specified in the Situm Dashboard formulary. For example:
Request when no language is specified (or when a language that has not been specified in the custom-fields is provided):
curl --location --request GET 'https://dashboard.situm.com/api/v1/pois' \
--header 'Authorization: Bearer <Token>'
Request for German language:
curl --location --request GET 'https://dashboard.situm.com/api/v1/pois' \
--header 'Accept-Language: de' \
--header 'Authorization: Bearer <Token>'
Mobile SDKs #
The SDKs use automatically the language set on the device and generate the API headers automatically (see previous API explanation). Therefore, the data is substituted automatically in the appropriate SDK fields with the corresponding translation. See Situm SDK Internationalization section for more information and a complete usage example.