Overlays

Place images on top of your image.

Let’s learn about placing images (overlays) on top of your main image.

We will work on a map and put some png points of interest (POI) in different places, learning about the different options we have.

POI Map

We will be working on this map of Europe. The image is at

https://cdn.ixmage.com/v2/grappler/images/demo/ov/map-eur.png?w=540

And we have these 3 images (Points Of Interest) we want to overlay on top of this map.

POI 1 https://cdn.ixmage.com/v2/grappler/images/demo/ov/pstop1.png
POI 2 https://cdn.ixmage.com/v2/grappler/images/demo/ov/pstop2.png
POI 3 https://cdn.ixmage.com/v2/grappler/images/demo/ov/pstop3.png

Learning By Examples

Let’s start by placing a POI on the map, without giving it any extra information:

Additional querystring data:
&overlay=u:https://cdn.ixmage.com/v2/grappler/images/demo/ov/pstop3.png

Overlays 1

We are using an overlay command to pass in the POI (Point Of Interest png) url.

Some behavior we can see:

The position is at the top-left corner (northwest).
The overlay png dimensions got bigger.

Let’s give the POI a width so that it sizes to its original 40px wide.

*w:40

Overlays 2

Now let’s see other parameters we can set to place our overlay:

*o:center

Overlays 3

adding the o parameter to the overlay command, we can set the position to one of the following:

northwest   north   northeast
west        center       east
southwest   south   southeast

Now our first POI is somewhere in Italy. Let’s make this particular POI a little bit bigger. The original png is 40x30 pixels, let us make this one a width of 80px, and a height of 60 pixels.

*w:80*h:60

Overlays 4

And to demonstrate some fine-tuning placement, let’s move it down, so that it does not block the name of Austria. For this, we will give the o: parameter some complexity by appending an offset in x, and an offset in y.

*o:center,2,30 - This will shift the POI placement, 2 pixels to the right, and 30 pixels down.

Overlays 5

Overlay Parameters

To summarize, here are the available parameters for working with overlay

param	name	default	description
u	url	-	REQUIRED The url of the image to overlay
o	offset	northwest,0,0	set a snapping point, and additional coordinate offsets for fine-tuning the placement
w	width	Original image width	width of the image to overlay
h	height	Original image height	height of the image to overlay

Multiple Overlays

More than one overlay is supported by adding more &overlay commands to the url.

(1) &overlay=u:image-url (2) &overlay=u:image2-url (3) &overlay=u:image3-url
(example, not actual url segment.)

Let’s add a second POI to our map, and place it inside Ukraine. We will start by placing it to snapping point east and work from there…

Additional data:
&overlay=u:images/demo/ov/pstop1.png*w:40*o:east

Overlays 6

Notice that in the url for this new overlay, I omitted some of the initial url segments. I did not include https://cdn.ixmage.com/v2/grappler/.

The overlay logic will know to add this initial data if your url starts with a known alias in your account. In this case “images” is a known alias for my account.

There is another step in logic where if the url does not have a protocol, and does not start with a known alias, then it is assumed that the current alias (the alias used for the main image) is being referenced.

The url parameter

Specifying the overlay url, these are the valid forms:

a complete url, containing protocol, domain, and file path and name
- Example: https://www.example.com/folder/subfolders/image.png
the portion of the url to access one of your images thru the service, specifying from your alias on…
- Example: alias/path/image.png
path to your image using the same alias as the base/main image.
- Example: path/image.png
- This will grab the image from the same alias as the base image.

Back to placing our second POI, we see it snapped to the east point on the main image, so we will move it left and up to place it to the left of the Ukraine text.

*o:east,60,-56 - offset 60px to the left, and 56px up.

Overlays 7

So 60 pixels to the left, and 56 pixels up placed it where I want it.

Let’s add a third one in Portugal to see how the o: coordinate system flips and flops depending on the snapping point used.

&overlay=u:images/demo/ov/pstop1.png*w:40*o:southwest,32,40

Overlays 8

In this case, the x offset goes right when positive, y offset also goes up. Basically when snapping south, positive y goes up, and when snapping north, positive y goes down.

On the same note, when snapping west, x offset goes right, and when snapping east, x offset goes left.

Doing negative values would make it move in the opposite direction.

One last one for Germany.

&overlay=u:images/demo/ov/pstop2.png*w:40*o:north,7,60

Overlays 8

The resulting url:

https://cdn.ixmage.com/v2/grappler/images/demo/ov/map-eur.png?w=540&overlay=u:https://cdn.ixmage.com/v2/grappler/images/demo/ov/pstop3.png*o:center,2,30*w:80*h:60&overlay=u:images/demo/ov/pstop1.png*w:40*o:east,60,-56&overlay=u:images/demo/ov/pstop1.png*w:40*o:southwest,32,40&overlay=u:images/demo/ov/pstop2.png*w:40*o:north,7,60

The Italy POI:
&overlay=u:https://cdn.ixmage.com/v2/grappler/images/demo/ov/pstop3.png*o:center,2,30*w:80*h:60

The Ukraine POI:
&overlay=u:images/demo/ov/pstop1.png*w:40*o:east,60,-56

The Portugal POI:
&overlay=u:images/demo/ov/pstop1.png*w:40*o:soutShwest,32,40

The Germany POI:
&overlay=u:images/demo/ov/pstop2.png*w:40*o:north,7,60