Hi all,
This post is the documentation for the plugin “Google Maps 3D + Drawing”
Demo page: https://paul-testing.bubbleapps.io/version-test/google_3d_map
Google’s blog announcement
It utilises Google’s new 3D Maps element and gives you the ability create 3D shapes (polygons and polylines) onto the map. Anyone already using the Google Maps Geometry/Drawing + W3W plugin, then the states which hold the shapes coordinates are compatible, so you can turn all your 2D shapes into 3D ones. Rectangles are Circles are not possible but they can be converted into polygons first and then rendered in 3D to display on the map.
IMPORTANT!
This functionality comes in the beta channel of the Google Maps API right now, so you cannot have any other Google Map plugin installed (unless you’re using my other 2D map plugin) and you cannot use Bubble’s geographic search box. When it moves out the beta channel, which I hope shouldn’t be that much longer I will update the plugin and any documentation. If you want to know how to set it up alongside my Google Maps Geometry/Drawing + W3W plugin, then set it up like this: paul-testing-1 | Bubble Editor
The plugin comes with a search box replacement called “AutocompleteWidget” which is a much better alternative, returning more place details. It’s also tied into the map element, so the map will pan to a selected place and put a marker at it’s location. The marker icons will change depending on the category the place falls in.
To see all the icons, you can refer to: https://developers.google.com/maps/documentation/places/web-service/icons#place-icon-and-background-color-requests
What options are included
Well, a fair bit… the main map element contains the vast majority of the settings. These are grouped into sections.
At the top, this is where three object states are defined. You need to populate these to see the data within these states. There’s also a debug mode option which just outputs additional data to the console (mainly for me really, in case of any issues or to help you out).
Top section
Markers
Select ‘Marker (Google Maps 3D)’ from the dropdown list. This contains a list of all markers currently on the map.
{
"address": "string value", // formatted address as text
"latitude": 1, // marker latitude coordinate
"longitude": 2, // marker longitude coordinate
"altitude": 3, // marker altitude coordinate
"icon": "string value", // marker icon url
"label": "string value", // the label seen over the marker
"popover": "string value", // the contents of any popover
"zindex": 1, // the stacking, zIndex order
"id": "string value" // unique id given to this marker
}
Shapes
Select ‘Shape (Google Maps 3D)’ from the dropdown list. This contains a list of all shapes currently on the map.
{
"type": "string value", // contains polygon or polyline'
"strokeColor": "string value", // shape's border color
"strokeWidth": 1, // shape's border width
"outerColor": "string value", // polyline only
"outerWidth": 1, // polyline only
"fillColor": "string value", // polygon only
"outerCoordinates": "string value", // polygons and polylines use this
"innerCoordinates": "string value", // polygons only, controls holes
"centerLatitude": 1, // shape's center latitude
"centerLongitude": 1, // shape's center longitude
"centerAltitude": 1, // shape's average center altitude
"popover": "string value", // the contents of any popover
"zindex": 1, // the stacking, zIndex order
"id": "string value", // unique id
"2dPerimeter": 1, // perimeter in meters
"3dPerimeter": 1, // perimeter in meters (includes altitudes)'
"2dSurfaceArea": 1, // surface area as m²
"3dSurfaceArea": 1, // surface area as m² (includes altitudes)
"bufferDistance": 1, // buffer distance away from main shape
"bufferInnerHole": 1, // buffer wall width in meters
"bufferStrokeColor": "string value", // buffer's border color
"bufferStrokeWidth": 1, // buffer's border width
"bufferFillColor": "string value", // buffer's fill color
"bufferId": "string value", // unique id, prefixed with 'buffer-'
"buffer2dPerimeter": 1, // perimeter in meters
"buffer3dPerimeter": 1, // perimeter in meters (includes altitudes)
"buffer2dSurfaceArea": 1, // surface area as m²
"buffer3dSurfaceArea": 1 // surface area as m² (includes altitudes)
}
Place
Select ‘Place (Google Maps 3D)’ from the dropdown list. This details from a selected place through the Autocomplete Widget.
{
"id": "string value", // the places id
"displayName": "string value", // the place display name
"svgIconMaskURI": "string value", // the icon url for the category the place falls in
"iconBackgroundColor": "string value", // a background color for the specific icon
"formattedAddress": "string value", // formatted address as text
"latitude": 1, // the place latitude coordinate
"longitude": 1 // the place longitude coordinate
}
Center
Latitude
Latitude in degrees. Values will be clamped to the range [-90, 90]. This means that if the value specified is less than -90, it will be set to -90. And if the value is greater than 90, it will be set to 90.
Longitude
Longitude in degrees. Values outside the range [-180, 180] will be wrapped so that they fall within the range. For example, a value of -190 will be converted to 170. A value of 190 will be converted to -170. This reflects the fact that longitudes wrap around the globe.
Altitude
Distance (in meters) above the ground surface. Negative value means underneath the ground surface.
Basics
Heading
The compass heading of the map, in degrees, where due north is zero. When there is no tilt, any roll will be interpreted as heading.
Range
The distance from camera to the center of the map, in meters.
Roll
The roll of the camera around the view vector in degrees. To resolve ambiguities, when there is no tilt, any roll will be interpreted as heading.
Tilt
The tilt of the camera’s view vector in degrees, value should be between 0 and 90. A looking directly down at the earth would have a tilt of zero degrees.
Altitude mode
Specifies how altitude components in the coordinates are interpreted. The ‘absolute’ option allows to express objects relative to the average mean sea level. This also means that if the terrain level of detail changes underneath the object, its absolute position will remain the same. The ‘clamp-to-ground’ option allows to express objects placed on the ground. They will remain at ground level following the terrain regardless of what altitude is provided. If the object is positioned over a major body of water, it will be placed at sea level. The ‘relative-to-ground’ option allows to express objects relative to the ground surface. If the terrain level of detail changes, the position of the object will remain constant relative to the ground. When over water, the altitude will be interpreted as a value in meters above sea level. The ‘relative-to-mesh’ option allows to express objects relative to the highest of ground + building + water surface. When over water this will be water surface, when over terrain this will be the building surface (if present) or ground surface (if no buildings).
Mode
Specifies a mode the map should be rendered in. Hybrid displays a transparent layer of major streets on satellite, or photorealistic imagery. Satellite displays satellite, or photorealistic imagery where available.
Disable UI
When true, all default UI buttons are disabled. Does not disable the keyboard and gesture controls.
Allow map click to stop animations
When true, a click on the map area will stop any animations that are currently in progress.
Adjust latitude
When fitting the map to include all markers or shapes, it will be centered based on their combined bounds. However, due to the map’s tilt angle, the objects might appear visually off-centre. To correct for this, you can provide an offset value to adjust the latitude. Increasing this value will shift the visible objects lower down on the map.
Bounds restrictions
Bounds south
South latitude in degrees. Values will be clamped to the range [-90, 90]. This means that if the value specified is less than -90, it will be set to -90. And if the value is greater than 90, it will be set to 90.
Bounds west
West longitude in degrees. Values outside the range [-180, 180] will be wrapped to the range [-180, 180). For example, a value of -190 will be converted to 170. A value of 190 will be converted to -170. This reflects the fact that longitudes wrap around the globe.
Bounds north
North latitude in degrees. Values will be clamped to the range [-90, 90]. This means that if the value specified is less than -90, it will be set to -90. And if the value is greater than 90, it will be set to 90.
Bounds east
East longitude in degrees. Values outside the range [-180, 180] will be wrapped to the range [-180, 180). For example, a value of -190 will be converted to 170. A value of 190 will be converted to -170. This reflects the fact that longitudes wrap around the globe.
Min/Max Restrictions
Min altitude
The minimum altitude above the ground which will be displayed on the map. A valid value is between 0 and 63170000 meters (Earth radius multiplied by 10).
Max altitude
The maximum altitude above the ground which will be displayed on the map. A valid value is between 0 and 63170000 meters (Earth radius multiplied by 10).
Min heading
The minimum angle of heading (rotation) of the map. A valid value is between 0 and 360 degrees. minHeading and maxHeading represent an interval of <= 360 degrees in which heading gestures will be allowed. minHeading = 180 and maxHeading = 90 will allow heading in [0, 90] and heading in [180, 360]. minHeading = 90 and maxHeading = 180 will allow heading in [90, 180].
Max heading
The maximum angle of heading (rotation) of the map. A valid value is between 0 and 360 degrees. minHeading and maxHeading represent an interval of <= 360 degrees in which heading gestures will be allowed. minHeading = 180 and maxHeading = 90 will allow heading in [0, 90] and heading in [180, 360]. minHeading = 90 and maxHeading = 180 will allow heading in [90, 180].
Min tilt
The minimum angle of incidence of the map. A valid value is between 0 and 90 degrees.
Max tilt
The maximum angle of incidence of the map. A valid value is between 0 and 90 degrees.
Dynamic markers & Dynamic shapes
Data type
Select your data type so you can see a list of available fields shown in the above image.
Data source
Supply a list of records for the specified data type.
Fields
The fields will become available once the above two options have been set.
Fit to bounds
This is applied once, when the markers/shapes are first loaded from the fields above. Allows the map to move to fit all markers/shapes in view. Depending on the camera tilt, the objects might appear off-centre. You can use the ‘Adjust latitude’ option above to help with this.
Marker options
Collision behavior
An enumeration specifying how a marker should behave when it collides with another marker or with any map labels. The ‘optional-and-hides-lower-priority’ option displays the marker only if it does not overlap with other markers. If two markers of this type would overlap, the one with the higher zIndex is shown. If they have the same zIndex, the one with the lower vertical screen position is shown. The ‘required’ option always displays the marker regardless of collision. The ‘required-and-hides-optional’ option always display the marker regardless of collision, and hide any ‘optional-and-hides-lower-priority’ markers or labels that would overlap with the marker.
Draws when occluded
Specifies whether this marker should be drawn or not when it’s occluded. The marker can be occluded by map geometry (e.g. buildings).
Extruded
Specifies whether to connect the marker to the ground. To extrude a marker, the altitudeMode must be either ‘absolute’ or ‘relative-to-ground’.
Size preserved
Specifies whether this marker should preserve its size or not regardless of distance from camera. By default, the marker is scaled based on distance from camera/tilt.
Icon types
Icon type
Specifies the type of marker icon to be used. The pin-element option creates a custom DOM element consisting of a shape with a balloon style (similar to the default marker) and an SVG glyph. You will need to supply the URL for an SVG file in your icon field, which will then be used for the glyph. The image-url option allows you to use your own custom image, but you must make sure the image is sized adequately since it cannot be resized/scaled. The svg-markup option also allows you to use your own custom image, but is SVG only. This should be the markup, for example: <svg … width=“56” height=“56” viewBox=“0 0 56 56” ….
Background
The background color of the pin shape.
Border color
The border color of the pin shape.
Scale
The scale of the pin.
Shape options
Occluded segments
Specifies whether parts of the shapes which could be occluded are drawn or not. Shapes can be occluded by map geometry (e.g. buildings).
Extruded
Specifies whether to connect the shape to the ground. To extrude a shape, the altitudeMode must be either ‘absolute’ or ‘relative-to-ground’.
Geodesic
When true, edges of the shapes are interpreted as geodesic and will follow the curvature of the Earth. When false, edges are rendered as straight lines in screen space.
Altitude behaviour
This option controls how altitude values are applied to shape coordinates on the map. If ‘always-override’ is selected, the altitude value specified below will be applied to all coordinates, regardless of whether they already have an altitude defined or not. If ‘only-if-missing’ is selected, the altitude value will only be applied to coordinates that do not have an existing altitude property. If ‘never-override’ is selected, no altitude values will be set or changed. Shapes without existing altitude data will be seen as 2D shapes.
Set altitude
Use this to set an altitude that will be used to override existing altitude properties within the coordinates of a shape. A value should be supplied here when the altitude behaviour option above is set to ‘always-override’ or ‘only-if-missing’.
Autocomplete Widget
Attribute ID
To allow the Autocomplete Widget to appear, create a group on your page and assign it this attribute ID. Because styling is limited, you should set the group’s height to a minimum value of 50px.
Use places icon
When true, the icon from the places request will be used as the icon on the map, otherwise it will be the standard red balloon icon.
Background color
The background color, this will override the color scheme.
Border color
The border color.
Border radius
The border radius (in pixels).
Color scheme
The color scheme to be applied.
Are there any states?
Yep, there’s a few, 24 at the time of writing this. Here they are with their descriptions.
-
marker clicked latitude
The latitude of a marker. Populated when a marker is clicked. -
marker clicked longitude
The longitude of a marker. Populated when a marker is clicked. -
marker clicked altitude
The altitude of a marker. Populated when a marker is clicked. -
marker clicked id
The unique Id of a marker. Populated when a marker is clicked. -
markers
Contains all markers currently on the map. -
map center latitude
The map center latitude. Populated when the map center position changes. -
map center longitude
The map center longitude. Populated when the map center position changes. -
map center altitude
The map center altitude. Populated when the map center position changes. -
map heading
The map heading. Populated when the map center position changes. -
map range
The map range. Populated when the map center position changes. -
map roll
The map roll. Populated when the map center position changes. -
map tilt
The map tilt. Populated when the map center position changes. -
map is ready
Will be set to true when the map is ready. -
place
Contains details from a selected place through the Autocomplete Widget. -
shapes
Contains all shapes currently on the map. -
shape clicked outer coordinates
The outer coordinates of a polygon/polyline. Populated when a polygon/polyline is clicked. -
shape clicked inner coordinates
The inner coordinates of a polygon. Populated when a polygon is clicked. -
shape clicked position latitude
The latitude at the clicked position inside a shape. Populated when a shape is clicked. -
shape clicked position longitude
The longitude at the clicked position inside a shape. Populated when a shape is clicked. -
shape clicked position altitude
The altitude at the clicked position inside a shape. Populated when a shape is clicked. -
shape clicked id
The unique Id of a shape. Populated when a shape is clicked. -
map clicked latitude
The latitude of the location clicked on the map. Populated when the map is clicked. -
map clicked longitude
The longitude of the location clicked on the map. Populated when the map is clicked. -
map clicked altitude
The altitude of the location clicked on the map. Populated when the map is clicked.
And surely there’s some actions right?
Of course! all actions and options detailed below for reference.
Fly to
This action moves the camera parabolically from the current location to a given end location over a given duration. It can also be used as a replacement for zooming and changing the camera angle.
Latitude
Latitude in degrees. Values will be clamped to the range [-90, 90]. This means that if the value specified is less than -90, it will be set to -90. And if the value is greater than 90, it will be set to 90.
Longitude
Longitude in degrees. Values outside the range [-180, 180] will be wrapped so that they fall within the range. For example, a value of -190 will be converted to 170. A value of 190 will be converted to -170. This reflects the fact that longitudes wrap around the globe.
Altitude
Distance (in meters) above the ground surface. Negative value means underneath the ground surface.
Heading
The compass heading of the map, in degrees, where due north is zero. When there is no tilt, any roll will be interpreted as heading.
Range
The distance from camera to the center of the map, in meters.
Roll
The roll of the camera around the view vector in degrees. To resolve ambiguities, when there is no tilt, any roll will be interpreted as heading.
Tilt
The tilt of the camera’s view vector in degrees. A view vector looking directly down at the earth would have a tilt of zero degrees. A view vector pointing away from the earth would have a tilt of 180 degrees.
Fly Duration
The duration of the fly animation in milliseconds. A duration of 0 will teleport the camera straight to the end position.
Fly Around
This option allows you to orbit the camera around the location for a specified duration, making the given number of rounds in that time.
Duration
The duration of the animation in milliseconds. This is the total duration of the animation, not the duration of a single rotation.
Rounds
The number of rounds to rotate around the center in the given duration. This controls the overall speed of rotation. Passing a negative number to rounds will cause the camera to rotate in a counter-clockwise direction instead of the default clockwise direction.
Stop On Click
Stops the animation when the map is clicked.
Create markers
This action allows you to create interactive 3D markers and add them to the map. You can also run it to update any existing markers without duplicating what is already on the map if any data changes. The 'Marker options' and 'Icon types' sections under the main element settings are also applied.
Data type
Select your data type so you can see a list of available fields.
Data source
Supply a list of records for the specified data type.
Fields
The fields will become available once the above two options have been set.
Fit to bounds
Allows the map to move to fit all markers in view. Depending on the camera tilt, the markers might appear off-centre. You can use the ‘Adjust latitude’ option in the main settings to help with this.
Trigger event
When set to true, allows the ‘markers created’ event to be triggered.
Remove markers
This action allows you to remove a single/list of markers from the map.
Marker (single)
Supply a marker to remove.
Marker (list)
Supply a list of markers to remove.
Remove all markers
This will remove all markers from the map, regardless of the options set above.
Change map properties
This action allows you to change some of the map properties.
Mode
Specifies a mode the map should be rendered in. Hybrid displays a transparent layer of major streets on satellite, or photorealistic imagery. Satellite displays satellite, or photorealistic imagery where available.
Disable UI
When true, all default UI buttons are disabled. Does not disable the keyboard and gesture controls.
Fullscreen
When true, the map will enter fullscreen.
Create shapes
This action allows you to create interactive 3D shapes and add them to the map. You can also run it to update any existing shapes without duplicating what is already on the map if any data changes. The 'Shape options' section under the main element settings are also applied. Note: If you have a set of coordinates that do not have an altitude, you can hardcode an altitude for all shapes using the 'Set altitude' setting.
Additionally, this action allows you to create a buffer area around the main shape. These will be applied to all shapes created. Each buffer area has a unique ID that can be seen in the ‘shapes’ state.
Data type
Select your data type so you can see a list of available fields.
Data source
Supply a list of records for the specified data type.
Fields
The fields will become available once the above two options have been set.
Generate buffer areas
Enables a buffer area (or contingency area) to be drawn around each shape.
Distance
Enter a value in meters that determines how far the buffer area is away from the main shape. Values can be positive or negative to determine the outward/inward distance from all sides.
Inner hole
Allows for an inner hole to be created inside the buffer area, forming a ring or wall effect. The value entered here (in meters) defines the thickness of the wall. If left empty, no hole will be created and the buffer area will consume the main shape.
Stroke color
Stroke color for the buffer area.
Stroke width
Stroke width for the buffer area.
Fill color
Fill color for the buffer area.
Fit to bounds
Allows the map to move to fit all shapes in view. Depending on the camera tilt, the shapes might appear off-centre. You can use the ‘Adjust latitude’ option in the main settings to help with this.
Trigger event
When set to true, allows the ‘shapes created’ event to be triggered.
Remove shapes
This action allows you to remove a single or list of shapes from the map.
Shape (single)
Supply a shape to remove.
Shape (list)
Supply a list of shapes to remove.
Remove buffer areas
This will remove any buffer areas from the supplied shapes above.
Remove all shapes
This will remove all shapes (and buffer areas) from the map, regardless of the options set above.
Fit to bounds
This action allows you to supply markers, shapes (or both) and fit the map to the boundaries of all.
Marker (single)
Supply a marker.
Markers (list)
Supply a list of markers.
Shape (single)
Supply a shape.
Shapes (list)
Supply a list of shapes.
Remove buffer areas
This action allows you to remove buffer areas from a single or list of shapes. The shape will remain both on the map and in the 'shapes' state.
Shape (single)
Supply a shape and it’s buffer area will be removed.
Shapes (list)
Supply a list of shapes and each shape’s buffer area will be removed.
Remove all buffers
This will remove all buffer areas from the map, regardless of the options set above.
Create buffer area
This action allows you to create a buffer area around a single or list of shapes.
Shape (single)
Supply a shape and it’s buffer area will be created.
Shapes (list)
Supply a list of shapes and each shape’s buffer area will be created.
Distance
Enter a value in meters that determines how far the buffer area is away from the main shape. Values can be positive or negative to determine the outward/inward distance from all sides.
Inner hole
Allows for an inner hole to be created inside the buffer area, forming a ring or wall effect. The value entered here (in meters) defines the thickness of the wall. If left empty, no hole will be created and the buffer area will consume the main shape.
Stroke color
Stroke color for the buffer area.
Stroke width
Stroke width for the buffer area.
Fill color
Fill color for the buffer area.
Events
-
map is ready
Triggers when the map is ready to interact with. -
markers created
Triggers when markers have been successfully created on the map. -
shapes created
Triggers when shapes have been successfully created on the map. -
place clicked
Triggers after a place has been clicked from the Autocomplete widget. -
marker clicked
Triggers when a marker has been clicked. -
shape clicked
Triggers when a shape has been clicked.
That pretty much covers everything for the time being. Any issues/problems/requests etc just let me know.
Paul