MapKiosk Documentation

1. Getting Started

MapKiosk launches with a full-screen map view. On first launch, the map centers on a default location (Las Vegas by default). You can change this in Preferences.

Opening Preferences

Mac: Use the keyboard shortcut or menu to open Settings. A password may be required if password protection is enabled.

iPad: Use one of these gestures to open Preferences:

• Three-finger tap: Tap the screen three times quickly with three fingers.
• Circle gesture: Draw a circle on the map with your finger.
• Welcome message tap: Tap the welcome message (if displayed) to open Preferences.

On first launch, iPad may show a "Preferences" button at the bottom of the screen for easy access.

2. Map Display & Styles

MapKiosk supports five map styles to suit different use cases:

• Standard: Classic road map with labels.
• Satellite: Aerial imagery.
• Hybrid: Satellite imagery with roads and labels overlaid.
• Fly Over: 3D satellite view with buildings and terrain.
• Fly Over Hybrid: 3D hybrid view with labels.

Default Map Type

In Preferences → Map, set the default map type. This is the style shown when the app starts.

Map Features

Toggle these options in the Map tab:

• Show Buildings: Displays 3D buildings on the map.
• Show Traffic: Shows real-time traffic conditions.
• Show Points of Interest: Displays POIs such as restaurants, parks, and landmarks.
• Show Scale: Displays a distance scale bar.
• Show Compass: Displays a compass for orientation.

Available Map Styles in Style Switcher

You can choose which map styles appear in the on-screen style switcher overlay. For example, if your kiosk only needs Standard and Satellite, disable the others to simplify the interface.

3. Welcome Message & Branding

The welcome message appears at the top of the map and helps orient users. You can fully customize its appearance.

Logo

Upload your organization's logo (PNG, JPEG, or TIFF). Images are automatically resized to a maximum of 256 pixels on the longest side and stored. Adjust the display size with the Logo Size slider (32–256 px).

Welcome Text

Edit the welcome message text. You can customize:

• Font size: Point size (e.g., 36 pt)
• Font: SF Pro, Helvetica, Arial, Times New Roman, Georgia, Verdana
• Color: Use the color picker
• Formatting: Bold, Italic, Underline

Background

Enable "Show Background" to add a colored background behind the welcome text. You can set the background color and opacity for better readability.

4. Search

MapKiosk includes a powerful search feature that finds addresses, businesses, points of interest, and more. Results come from multiple sources:

• Address geocoding: Street addresses, cities, landmarks
• Local search: Businesses and POIs in the current map area
• Natural language: Queries like "coffee shops" or "museums"

Using Search

Type your query in the search field and click the action button (e.g., "View"). Up to 12 results appear in a dropdown. Select a result to pan and zoom the map to that location and add a temporary pin.

Search Button

In Preferences → Controls, you can change the search button caption (e.g., "View", "Go", "Search") and its color.

Search Restrictions

For kiosks in a specific area, you can restrict search results:

• None: No restriction
• Zoom Level: Only results within the current visible map area
• City: Restrict to a specific city (enter city name)
• State: Restrict to a state or province
• Country: Restrict to a country

Enter the restriction value (e.g., "Las Vegas", "Nevada", "USA") in the Restriction Value field.

5. Location & Navigation

Configure where the map starts and how users can navigate.

Starting Location

Set the default location in two ways:

• Address: Enter a street address, city, or landmark (e.g., "Fremont Street, Las Vegas, NV, USA")
• Coordinates: Enable "Use Coordinates" and enter latitude and longitude (e.g., 36.1699, -115.1398)

Zoom Levels

Control zoom behavior with three sliders:

• Default Zoom Level: Initial zoom when the app starts
• Minimum Zoom: Users cannot zoom out past this level
• Maximum Zoom: Users cannot zoom in past this level

Restore After Inactivity

Enable "Restore default location and style after 5 minutes of inactivity" to automatically return the map to the starting location and default map style when no one has interacted with the map for 5 minutes.

Restrict Navigation to Region

For kiosks that should stay within a defined area, enable "Restrict navigation to a region." Choose the restriction level:

• Map view: Same area as the default zoom
• City level: Approximately 10× the default view
• State level: Approximately 100× the default view
• Country level: Approximately 1000× the default view

Restriction is relative to the default address and zoom level. Users cannot pan or zoom outside the allowed region.

6. Custom Pins

Add custom markers to highlight locations such as entrances, departments, or points of interest.

Adding a Pin

Click "Add Pin" in Preferences → Pins. Enter:

• Pin Title: Main label (e.g., "Main Entrance")
• Description: Optional subtitle
• Location: Use an address or coordinates (latitude/longitude)
• Icon: Choose from 50+ SF Symbols (map pin, building, car, hospital, etc.)
• Icon Color: Customize the pin color

Pin Display

Pins scale with zoom level for better visibility. Clicking a pin shows a callout with its title and subtitle.

CSV Import & Export

Manage pins in bulk with CSV:

Format: title,subtitle,address,latitude,longitude,iconName,iconRed,iconGreen,iconBlue

Example: Museum,Main entrance,,36.1699,-115.1398,building,0.0,0.5,1.0

Leave address empty if using coordinates. Icon colors are RGB values from 0.0 to 1.0. Import supports both header and headerless CSV files.

Trial mode: Limited to 3 custom pins. A full license allows unlimited pins.

7. Overlay Controls

Floating controls appear on top of the map. You can show or hide each control and choose where it appears.

Visible Controls

• Show Search Field: Displays the search bar at the top
• Show Zoom Controls: +/- buttons for zooming
• Show Style Switcher: Buttons to switch between map styles

Positioning

Each control can be placed in one of four corners:

• Top-Left
• Top-Right
• Bottom-Left
• Bottom-Right

When zoom controls and style switcher are in the same corner, they stack vertically.

Border Distance

Adjust the distance (in pixels) from the screen edges. Range: 20–200 px.

8. Fly Over Mode & 3D Controls

When "Fly Over" or "Fly Over Hybrid" is selected, MapKiosk shows 3D camera controls in the opposite corner from the zoom controls.

3D Camera Controls

• View Angle: Up/down arrows adjust the pitch (viewing angle)
• Rotate: Left/right arrows rotate the view around the center
• Distance: +/- buttons change the camera altitude (zoom in 3D)
• Reset: Orange button restores the camera to default settings

Use the Reset button if the 3D view becomes misaligned or stuck.

9. Security & Kiosk Mode

Most security options are available on Mac only. Trial mode restricts some features.

Kiosk Mode (Mac)

• Hide Menu Bar and Dock: Full-screen kiosk experience
• Don't Allow Force Quit: Prevents Cmd+Option+Esc from quitting
• Hide Quit Menu: Removes Quit from the app menu
• Don't Allow Process Switching: Keeps users in MapKiosk (no Cmd+Tab)

Password Protection

Enable "Protect Preferences Access" and set a password. Users must enter the password to open Preferences. Add a hint to help authorized users.

Keep App in Front

"Keep the App in Front of other Apps" ensures MapKiosk stays on top. Useful when other apps might accidentally take focus.

Auto-Start & Auto-Restart

• Open at Login: MapKiosk starts when the Mac boots
• Restart Automatically: Uses a background agent to relaunch MapKiosk if it quits. Requires approval in System Settings → Login Items

Power Management

• Allow System Sleep: Lets the Mac sleep when idle
• Allow Display Sleep: Lets the display sleep when idle

Disable these for 24/7 kiosks that should stay on.

10. Mac vs iPad Differences

Technical Notes

Search Result Types

Search combines geocoding (addresses), MKLocalSearch (businesses and POIs), natural language queries, and category-based search (e.g., "restaurant", "museum"). Results are deduplicated and filtered by region restrictions.

Memory & Performance

MapKiosk uses an annotation image cache to avoid regenerating pin icons. Under memory pressure, the cache is cleared. Temporary search pins are also cleared in critical memory situations.

Region Restriction Logic

Region restriction is based on the default location and a span multiplier (Map view: 1×, City: 10×, State: 100×, Country: 1000×). The map center and span are constrained so users cannot navigate outside the allowed area.