Skip to main content

Image Overlay

The ImageOverlay object is used to help with displaying an image overlay on the map.

ImageOverlay extends Overlay.

The ImageOverlay has the following characteristics:

  • The image is added into an Overlay div.
  • The Overlay div if the element that is positioned on the map.
  • You can rotate the image within the Overlay div.
  • The image will be aligned to the top left of the Overlay div.

Creating the image overlay​

You can use the G.imageOverlay() function to get your own image overlay object.

G.imageOverlay(): ImageOverlay

const image = G.imageOverlay();

Positioning the image on the map​

It can be a little tedious to get precise positioning on a map, especially if you also need to rotate the image. To help with this you can use the drag and resize features of the Overlay and the rotate feature of the Image Overlay to get the image in the right spot. Using the event callbacks you can console log the image rotate and the latitude longitude bounds of the overlay. You can then use that to set your final position and rotation.

// Set up your map
const map = G.map('#map1', {
    center: { latitude: 44.3644077301405, longitude: -68.32022737144165 },
    zoom: 16,
});
map.show();

// Create the image object
const imageOverlay = G.imagOverlay({
    bounds: {
        ne: [44.36877953646439, -68.31675122855835], // Northeast corner
        sw: [44.361063461552426, -68.32760881065063], // Southwest corner
    },
    image: 'https://developers.google.com/maps/documentation/javascript/examples/full/images/talkeetna.png',
    drag: true,
    resize: true,
    rotate: true,
    map: map,
    opacity: 0.5 // So that we can see the map through the imag
});

// Make sure that the Overlay is the same shape as the image
imageOverlay.fitToImage();

/**
 * Get the debug information for the image overlay
 *
 * @returns {object} The debug information
 */
const getDebugInfo = () => {
    const bounds = imageOverlay.getBounds();
    return {
        angle: imageOverlay.getRotation(),
        bounds: {
            ne: bounds.getNorthEast().toJson(),
            sw: bounds.getSouthWest().toJson(),
        }
    };
};

// Console log the information we need when dragging ends
imageOverlay.on('dragend', () => {
    console.log('Drag End: ', getDebugInfo());
});
// Console log the information we need when resizing ends
imageOverlay.on('resizeend', () => {
    console.log('Resize End: ', getDebugInfo());
});
// Console log the information when the rotation ends
imageOverlay.on('rotateend', () => {
    console.log('Rotation End:', getDebugInfo());
});

Rotating the image overlay​

You can configure that the image overlay can be rotated by clicking on a rotate handle and moving the mouse. If this is enabled then a border will be added to the image to make it easier to see the dimensions and a ration handle will be added to the image.

In order for the mouse events to apply to the overlay, the image overlay will be added to a different layer on the Google map. By default the overlay is added to the overlayLayer pane. If dragging is enabled then it will be added to the float pane. This means that it will be above markers and polylines.

ImageOverlay options​

Type ImageOverlayOptions

OptionTypeDefaultDescription
boundsLatLngBoundsThe latitude and longitude bounds where the image should be displayed.
classNamestringThe class name for the image element.
debugbooleanfalseWhether to set a background and border on the overlay div that the image is in to help show where the image is being displayed. When adding an image sometimes you want to see the overlay container that it is in. This will had a semi-transparent red background and red border to the overlay div to make it visible.
dragbooleanfalseWhether the image overlay can be dragged around the map.
imageUrlstringThe URL for the image to display.
mapMapThe map to add the image overlay to.
opacitynumber0The opacity of the image (0.0 to 1.0).
resizebooleanfalseWhether the overlay can be resized.
rotationnumberfalseThe initial rotation angle in degrees (0 to 360).
rotationbooleanfalseWhether the image can be rotated.
stylesobjectAn object of CSS styles that will be applied to the image element. This is for setting or retrieving all styles. If you need to set an individual style then use the style() method. This will merge the styles with the existing styles.

Events​

Below are the available image overlay events

EventDescription
rotateendThe event fired when the rotating finishes.
rotateThe event fired each time the rotating updates the image overlay rotation.
rotatestartThe event fired when rotating the image overlay starts.

rotateend​

Called when the rotating the overlay ends.

imageOverlay.on('rotateend', () => {
    // Do something here
});

// You can also use the event constant
imageOverlay.on(G.ImageOverlayEvents.ROTATE_END, () => {
    // Do something here
});

// Or, use the callback method
imageOverlay.onRotateEnd(() => {
    // Do something here
});

rotate​

Called when the rotating updates the overlay position.

imageOverlay.on('rotatestart', () => {
    // Do something here
});

// You can also use the event constant
imageOverlay.on(G.ImageOverlayEvents.ROTATE, () => {
    // Do something here
});

// Or, use the callback method
imageOverlay.onRotate(() => {
    // Do something here
});

rotatestart​

Called when the overlay is starting to be rotateged.

imageOverlay.on('rotatestart', () => {
    // Do something here
});

// You can also use the event constant
imageOverlay.on(G.ImageOverlayEvents.ROTATE_START, () => {
    // Do something here
});

// Or, use the callback method
imageOverlay.onRotateStart(() => {
    // Do something here
});

Properties​

PropertyTypeDescription
boundsLatLngBoundsThe latitude and longitude bounds where the image should be displayed.
classNamestringThe class name for the image element.
imageUrlstringThe URL for the image to display.
opacitynumberThe opacity of the image (0.0 to 1.0).
rotatebooleanWhether the image can be rotated.
rotationnumberThe rotation angle in degrees (0 to 360).
stylesobjectAn object of CSS styles that will be applied to the image element. This is for setting or retrieving all styles. If you need to set an individual style then use the style() method. This will merge the styles with the existing styles.

bounds​

Get and set the latitude and longitude bounds where the image should be displayed. The value is a valid LatLngBounds value.

// Get the value
const bounds = imageOverlay.getBounds();
// Set the bounds
imageOverlay.bounds = {
    ne: [44.36877953646439, -68.31675122855835], // Northeast corner
    sw: [44.361063461552426, -68.32760881065063], // Southwest corner
}
// Or
imageOverlay.bounds = G.latLngBounds({
    ne: G.latLng(44.7, -70.8),
    sw: G.latLng(44, -68),
});
// Or any of the other LatLngBounds value types

className​

Get and set the class name of the image overlay. If you need multiple class names then separate them with a space.

// Get the class name
const className = imageOverlay.className;
// Set the class name
imageOverlay.className = 'my-class-name';
// Set multiple class names
imageOverlay.className = 'my-class-name another-class';

imageUrl​

Get and set the URL of the image to display.

// Get the image URL
const url = imageOverlay.imageUrl;
// Set the image url
imageOverlay.imageUrl = 'https://www.image.com/path/to/image.jpg';

opacity​

Get and set the opacity of the image

// Get the opacity
const opacity = imageOverlay.opacity.
// Set the opacity
imageOverlay.opacity = 0.5;
imageOverlay.opacity = 1;

rotate​

Get or set whether the overlay can be rotated by dragging the rotate handle.

// Get the rotate value
const canRotate = imageOverlay.rotate;
// Set that the image can be rotated
imageOverlay.rotate = true;
imageOverlay.rotate = false;

rotation​

Get or set the rotation degree for the image.

// Get the rotation value
const rotation = imageOverlay.rotation;
// Set the rotation value
imageOverlay.rotation = 45;
imageOverlay.rotation = 325;

styles​

Get the inline styles for the overlay or bulk set multiple styles.

// Get the styles
const styles = imageOverlay.styles;
// Set multiple styles
tooltip.styles = {backgroundColor: '#ff0000', color: '#fff'}

Methods​

constructor​

constructor(objectType: string, testObject: string, testLibrary?: string)

The class object constructor.

ParameterTypeRequiredDescription
objectTypestringYesThe object type. i.e. "map", "marker", "tooltip". Used with the object type tests in Base.
testObjectstringYesThe camel case object name that is used when testing for the existance of the Google Map library. This should be the name of the object that calls this method.
testLibrarystringAn optional Google maps library class to check for. This needs to be part of the google.maps object. If not set then it's set to testObject.

disableRotation​

disableRotation(): ImageOverlay

Set that the image can not be rotated with a rotation handle.

imageOverlay.disableRotation();

display​

display(map: Map): Promise<ImageOverlay>

Add the image overlay to the map and display it. This is an alias to show().

ParameterTypeRequiredDescription
mapMapYesThe map object
imageOverlay.display(map);

enableRotation​

enableRotation(): ImageOverlay

Set that the image can be rotated with a rotation handle. This is useful for figuring out the final rotation value.

imageOverlay.enableRotation();

fitToImage​

fitToImage(): Promise<ImageOverlay>

Adjust the overlay div that the image is in to match the current dimensions of the image. If resizing is enabled then this will also constrain the resizing to match the aspect ratio of the image.

imageOverlay.fitToImage();

getBounds​

getBounds(): LatLngBounds

Get the latitude/longitude bounds for where the image will be displayed.

const bounds = imageOverlay.getBounds();

getContainerLatLngFromPixel​

Computes the geographical coordinates from pixel coordinates in the map's container.

This is a shortcut to getting the projection from the overlay and then calling fromContainerPixelToLatLng on the projection with the pixel value.

ParameterTypeRequiredDescription
xnumber | PointValueYesThe x pixel value, or a PointValue.
ynumberThe y pixel value if x is a number.
const latLng = mapOverlay.getContainerLatLngFromPixel(xValue, yValue);
const latLng = mapOverlay.getContainerLatLngFromPixel({x: xValue, y: yValue});
const latLng = mapOverlay.getContainerLatLngFromPixel(G.point({x: xValue, y: yValue}));

getDivLatLngFromPixel​

Computes the geographical coordinates from pixel coordinates in the div that holds the draggable map.

This is a shortcut to getting the projection from the overlay and then calling fromDivPixelToLatLng on the projection with the pixel value.

ParameterTypeRequiredDescription
xnumber | PointValueYesThe x pixel value, or a PointValue.
ynumberThe y pixel value if x is a number.
const latLng = mapOverlay.getDivLatLngFromPixel(xValue, yValue);
const latLng = mapOverlay.getDivLatLngFromPixel({x: xValue, y: yValue});
const latLng = mapOverlay.getDivLatLngFromPixel(G.point({x: xValue, y: yValue}));

getImageUrl​

getImageUrl(): string

Get the URL of the image that is being displayed.

const url = imageOverlay.getImageUrl();

getOpacity​

getOpacity(): number

Get the opacity of the image.

const opacity = imageOverlay.getOpacity();

getRotation​

getRotation(): number

Get the rotation angle in degrees

const rotation = imageOverlay.getRotation();

onRotateEnd​

onRotateEnd(callback: EventCallback): void

Callback for when the rotating the image ends.

This is a convenience function for imageOverlay.on(G.ImageOverlayEvents.ROTATE_END, callback).

ParameterTypeRequiredDescription
callbackFunctionYesThe callback function that will be called when the event is dispatched.

Callback function parameters

ParameterTypeDescription
eventMouseEvent|TouchEventThe browser mouse or touch event
imageOverlay.onRotateEnd((event, change) => {
    // Do something
    const newBounds = imageOverlay.getBounds()
})

onRotate​

onRotate(callback: EventCallback): void

Callback for when the rotating the overlay updates the overlay position. This is called multiple times while the overlay is being rotated.

This is a convenience function for imageOverlay.on(G.ImageOverlayEvents.ROTATE, callback).

ParameterTypeRequiredDescription
callbackFunctionYesThe callback function that will be called when the event is dispatched.

Callback function parameters

ParameterTypeDescription
eventMouseEvent|TouchEventThe browser mouse or touch event
cornerstringThe corner that is the rotating is happening at. ne, nw, se, or sw.
imageOverlay.onRotate((event, corner) => {
    // Do something
})

onRotateStart​

onRotateStart(callback: EventCallback): void

Callback for when the rotating the overlay starts.

This is a convenience function for imageOverlay.on(G.ImageOverlayEvents.ROTATE_START, callback).

ParameterTypeRequiredDescription
callbackFunctionYesThe callback function that will be called when the event is dispatched.

Callback function parameters

ParameterTypeDescription
eventMouseEvent|TouchEventThe browser mouse or touch event
cornerstringThe corner that is the rotating is happening at. ne, nw, se, or sw.
imageOverlay.onRotateStart((event, corner) => {
    // Do something
})

removeClassName​

removeClassName(className: string): Overlay

Removes a class name from the image overlay element.

ParameterTypeRequiredDescription
classNamestringYesThe class name(s) to remove from the overlay element.
imageOverlay.removeClassName('my-class');

If you need to remove multiple class names then separate them with a space.

imageOverlay.removeClassName('my-class another-class');

setBounds​

setBounds(bounds: LatLngBoundsValue): ImageOverlay

Set the bounds where the image should be displayed.

ParameterTypeRequiredDescription
boundsLatLngBoundsYesThe latitude and longitude bounds where the image should be displayed.
// Set the bounds
imageOverlay.setBounds({
    ne: [44.36877953646439, -68.31675122855835], // Northeast corner
    sw: [44.361063461552426, -68.32760881065063], // Southwest corner
});
// Or
imageOverlay.setBounds(G.latLngBounds({
    ne: G.latLng(44.7, -70.8),
    sw: G.latLng(44, -68),
}));
// Or any of the other LatLngBounds value types

setClassName​

setClassName(className: string): Overlay

Set the class name(s) for the overlay element.

ParameterTypeRequiredDescription
classNamestringYesThe class name(s) to set on the overlay element.
imageOverlay.setClassName('my-class');

If you need to add multiple class names then separate them with a space.

imageOverlay.setClassName('my-class another-class');

setImageUrl​

setImageUrl(imageUrl: string): ImageOverlay

Set the URL of the image to display.

ParameterTypeRequiredDescription
imageUrlstringYesThe URL of the image to display.
imageOverlay.setImageUrl('https://developers.google.com/maps/documentation/javascript/examples/full/images/talkeetna.png');

setOpacity​

setOpacity(opacity: number): ImageOverlay

Set the opacity of the image.

ParameterTypeRequiredDescription
opacitynumberYesThe opacity number between 0 and 1.
imageOverlay.setOpacity(0.5);

setOptions​

setOptions(options: ImageOverlayOptions): Marker

Set the options for the image overlay.

ParameterTypeRequiredDescription
optionsImageOverlayOptionsYesThe image overlay options.
imageOverlay.setOptions({opacity: 0.5, className: 'image-class'});

setRotation​

setRotation(rotation: number): ImageOverlay

Set the rotation angle in degrees.

ParameterTypeRequiredDescription
rotationnumberYesThe rotation angle in degreess.
imageOverlay.setRotation(34);

setStyles​

setStyles(styles: object): Overlay

Set one more styles for the image overlay element. This will merge styles with an existing ones.

ParameterTypeRequiredDescription
stylesobjectYesObject of key => value pairs of CSS styles to set on the element.
imageOverlay.setStyles({ backgroundColor: '#333', border: '2px solid #ff0000' });

style​

style(key: string, value: string): Overlay

Add a single style to the image overlay wrapper div.

ParameterTypeRequiredDescription
namestringYesThe style name. For example, color or backgroundColor.
imageOverlay.style('border', '3px solid #ff0000');

toggle​

toggle(map: Map): void

Toggle the display of the image overlay on the map.

ParameterTypeRequiredDescription
mapMapYesThe map object
imageOverlay.toggle(map);