Improving khtml.maplib

This page describes a historic artifact in the history of OpenStreetMap. It does not reflect the current situation, but instead documents the historical concepts, issues, or ideas.

About: This page describes historic Google Summer of Code 2011 improvements to a meanwhile discontinued JavaScript library for slippy maps.
Reason for being historic: The khtml.maplib project is dead. Its author recommends to use Leaflet instead.

This project has been approved for the Google Summer of Code 2011.

Its general purpose is to improve the OpenSource JavaScript Slippy WebMap Library khtml.maplib.

As this GSoC-project is already finished, this site will not be maintained any more. The API and the code for khtml.maplib may still change, so please see Simple_marker_API for more up to date information or the JSdoc API-documentation that comes in the tar-ball with khtml.maplib.

Project Ideas

Developing an easily integratable marker system for khtml.maplib.
Design a webpage for the khtml.org server, where users can design their maps via drag & drop, place markers and automatically get the code generated to integrate the webmap into their website.

Already existing interface

There is already a very simple implementation for a marker system, but it is still very inconvenient for the user and has a lack of features.It only lets the user add dom elements as an overlay.

For an example see section Markers in khtml-help.

Improvements

increasing features for markers (make them dragable, clickable, infobubble with text, ...)
improving interface, making it easier to integrate into own website

Approach

learning Object Oriented JavaScript
researching marker interfaces from other webmap-services (Google Maps, Bing, Yahoo, ...)
developing own interface for markers

Prospective Timeline

~~April 26th~~: Starting intensive research when I am accepted for the project. Involving in the community, collecting ideas, discussing with mentor, summarizing, …
~~May 30th~~: Starting development. Writing code, testing performance, ...
~~July 2nd~~: When all my exams are over, I will have plenty of time to work on the project. Letting others test my code.
~~July 11th~~: Submit intermediate results for evaluations.
~~August 8th~~: Starting final testing and debugging. Finishing documentation.
~~August 15th~~: Hand In date.
August 22nd: Deadline

Actual Timeline

~~April 26th~~: Started research phase.
~~June 15th~~: Started programming phase.
~~July 2nd~~: All exams finished. Working heavily to catch up with timeline.
~~July 11th~~: Had a great progress so far (see updates). Submitted evaluations. Think I have caught up with the original timeline.
~~August 8th~~: Tested with many different browsers on different systems.
~~August 15th~~: Started final documentation work.

Project Progress

Update 1: May 15th

Research

I did a lot of online research on marker APIs of

Google Maps Markers,

Yahoo YMarkers and

BING Pushpins.

I read some ebooks about

OpenStreetMaps,

Mapscripting 101,

Google Maps API V3 and

Object-oriented JavaScript.

Preliminary work

I started a mailinglist especially for khtml: kthml.maplib@freelists.org

( to join, send an email with "subscribe" in the header to khtml.maplib-request@freelists.org)

Update 2: June 30th

Due to heavy workload on other projects at university, I could not start as early as planned, but now as all my exams are over, I am already really into coding and testing. I am now about 2 weeks behind the planned timeline.

I used khtml.maplib for another project at my university. It is called SharedPainting and a form of collaborative painting tool. khtml is used for pinch/zoom navigation in the PaintingOverview. Each drawing-area is one tile in the form of map-tiles. Therefore I crawled really deep into the sourcecode of khtml and found nearly by chance some bugs, that I fixed.

If you are interested, goto SharedPainting with you iPhone or iPod touch.

On desktop PCs use this link

Note: It is still very buggy and only optimized for iPhone-screen, since it's supposed to be a mobile application.

Bugfixes

When using touch-zooming with 2 fingers and you reach the maximum zoom level, the map suddenly jumps a few centimeters and jumps back if you drag your fingers towards each other again.

The problem was here. The zoomDelta is set to a fixed value (1) that causes the jump. I used a flag to store the old value.

        if (evt.touches.length == 2) {
            this.mousedownTime = null;
            var X1 = evt.touches[0].pageX;
            var Y1 = evt.touches[0].pageY;
            var X2 = evt.touches[1].pageX;
            var Y2 = evt.touches[1].pageY;
            var Distance = Math.sqrt(Math.pow((X2 - X1), 2) + Math.pow((Y2 - Y1), 2));
            var zoomDelta = (Distance / this.startDistance);
            var zz = this.startZZ + zoomDelta - 1;
            if (zz < 1) {
                zz = 1;
            }
            if (zz > this.tileSource.maxzoom) {
                zz = this.tileSource.maxzoom;
                zoomDelta = 1;
            }
            var x = (X1 + X2) / 2;
            var y = (Y1 + Y2) / 2;
 
            faktor = Math.pow(2, zz);
            var zoomCenterDeltaX = x / faktor - this.width / 2;
            var zoomCenterDeltaY = y / faktor - this.height / 2;
            var f = Math.pow(2, zoomDelta - 1);
            var dx = zoomCenterDeltaX - zoomCenterDeltaX * f;
            var dy = zoomCenterDeltaY - zoomCenterDeltaY * f;
 
            this.moveX = (x + dx) / faktor + this.startMoveX;
            this.moveY = (y + dy) / faktor + this.startMoveY;
 
            var center = new khtml.maplib.Point(this.lat, this.lng);
            this.setCenter2(center, zz);
        }

I replaced it with:

if (zz > this.tileSource.maxzoom) {
	zz = this.tileSource.maxzoom;
	zoomDelta = this.zoomDeltaOld;
}
else
	this.zoomDeltaOld = zoomDelta;

Here are the two testcases: before bugfix #1 and after bugfix #1

Only on touchscreen-devices! Zoom in to maximum zoomlevel with two fingers and watch the map jumping.

Again with touch-zooming and panning. When you first use one finger to drag the map, then apply a second one to zoom and then release one finger and continue dragging with the other one, the map stays still and does not move any more.

I located the problem here:

this.end = function (evt) {
        if (evt.preventDefault) {
            evt.preventDefault(); // The W3C DOM way
        } else {
            evt.returnValue = false; // The IE way
        }
        window.clearInterval(this.zoomOutInterval);
        this.zoomOutStarted = false;
	this.zoomOutSpeed = 0.01;
 
        if (evt.touches.length == 0) {
            this.moveok = true;
            if (this.moveAnimationMobile) {
                if (this.moveAnimationBlocked == false) {
                    var speedX = this.lastMoveX - this.moveX;
                    var speedY = this.lastMoveY - this.moveY;
                    clearTimeout(this.animateMoveTimeout);
                    this.animateMove(speedX, speedY);
                }
            }
        }
        
    }

I added this to avoid the problem. It's the same calculation that is done, when a second finger touches the screen, but now I also do it, when the second finger is removed.

if (evt.touches.length == 1) {
        this.moveok = true;
	this.startMoveX = this.moveX - evt.touches[0].pageX / this.faktor / this.sc;
        this.startMoveY = this.moveY - evt.touches[0].pageY / this.faktor / this.sc;
}

Here are the two testcases: before bugfix #2 and after bugfix #2

Only on touchscreen-devices! Drag with one finger, then apply the second one to zoom and then release one finger and try dragging.

When double-tap zooming on a map that's not fullscreen, but only a part of the screen, the map doesn't calculate the offsetLeft and offsetTop of the map and so often zooms the tapped point out of the view, especially when it's near the edge.

The problem was here:

    this.autoZoomIn = function (x, y, z) {
        //console.log(x,y,z);
        if (this.autoZoomInTimeout) {
            window.clearTimeout(this.autoZoomInTimeout);
        }
        var stepwidth = 0.20;
	
        if (z < 0) {
		stepwidth = -stepwidth
        }
        zoomGap = false;
        if (Math.abs(z) <= Math.abs(stepwidth)) {
            zoomGap = true;
        }
        //this.hideOverlays();
        var dzoom = stepwidth;
        var zoom = this.position.zoom + dzoom;
        zoom = Math.round(zoom * 1000) / 1000;
        if (zoomGap) {
		//console.log("---: "+z+":"+zoom);
			if(z<0){
			    zoom = Math.floor(zoom);
			}else{
			    zoom = Math.ceil(zoom -0.2);
			}
		
		//console.log("---"+zoom);
            //dzoom = z;
            dzoom = zoom - this.position.zoom ;
            //console.log("gap: "+dzoom+" : "+zoom);
        }
 
        faktor = Math.pow(2, zoom);
        var zoomCenterDeltaX = x - this.width / 2;
        var zoomCenterDeltaY = y - this.height / 2;
        var f = Math.pow(2, dzoom);
 
        var dx = zoomCenterDeltaX - zoomCenterDeltaX * f;
        var dy = zoomCenterDeltaY - zoomCenterDeltaY * f;
 
        var that = this;

I substracted the top and left attributes of the map:

        var zoomCenterDeltaX = (x - this.mapLeft) - this.width / 2;
        var zoomCenterDeltaY = (y - this.mapTop) - this.height / 2;

Here are the two testcases: before bugfix #3 and after bugfix #3

Only on touchscreen-devices! Double tap on a point at the left edge of the map and watch it move away.

There is a similar bug with the 2 finger zoom and non fullscreen map, which I was able to locate roughly but could not fix so far.

Update 3: July 7th

During the last week I started implementing a marker-interface for khtml.maplib and played around a little bit, to make it good looking with nice cursors.

Markers

There was already a very simple marker interface, as you can see here and here (scroll down to section markers).

I did a lot of research and comparison on Google Maps, Microsoft Bing Maps, Yahoo Maps and also OpenLayers.

Google Maps has by far the most complex structure in their DOM-tree, but still is the most powerful Maps API with a lot of features.

But for the normal user it is still very easy to implement.

Only few lines of code are needed, to get a moveable standard marker with a shadow for 3D-effect and a nice drag and drop animation.

var marker = new google.maps.Marker({
                position: new google.maps.LatLng(18, 48),
                map: map,
                draggable: drag,
                title: "Marker #1"             
             });

example on Google Maps JavaScript API V3

And only some more lines are needed to get a nice litte infowindow:

google.maps.event.addListener(marker, 'click', function() {
		var infowindow = new google.maps.InfoWindow({
			content: "This is " + this.getTitle() + " and you just clicked it!"
		});
		infowindow.open(map,this);
	});

example on Google Maps JavaScript API V3

First I started to analyze the existing marker interface and soon found out, that using 2 divs where the marker is placed in, is 1 too much (source code). I started playing around with the code and very soon got a working version with only one div (source code).

For testing and comparing the performance of the different maps, I found some nice codes on mappertests.codeplex.com, which I took and modified a little bit, to meet my requirements.

Try the two versions with many markers (>1000) and see the difference in the time:

original version (2 divs): performance test
simplified version (1 div): performance test

On my computer i got an perfomance increase when generating the markers of about 10%. Of course this performance tests highly depend on which browser you use and how powerful your computer is.

Compared to the other Maps, it's quite fast, but still lacks features:

Google Maps: performance test
Yahoo Maps: performance test
Microsoft Bing: performance test

Only Google Maps is much faster in this test than the other, because

they don't create DOM-elements for normal markers, but place the images on a canvas ( watch this video for this interesting topic)
when creating draggable markers, they use normal DOM-elements, but the timer stops much earlier than the markers appear. I have not found a solution for this problem so far.

The next step was, to increase the features of the marker and the interface. I added:

EventListeners for touch-events,
a nice DragAnimation like Google-Markers and
the possibility to define a shape for custom markers

Here you can try the current version: markers with increased features

Of course these features have a heavy influence on the performance: performance test with increased features

I designed a nice little marker in photoshop:

With the help of this homepage, I also made a shadow for it:

And I decided to embed it as standard marker via data-URI, base 64 directly in the source code. This tool helped me with that.

But since IE6 and IE7 don't support data-URI, I had to do a workaround and provide the images as separate files as well (IE8 works with data-URI).

IE6 also has problems with transparent PNGs, so I had to do another workaround for that. I tried a special "filter"-method Microsoft provides for this case (see here). It worked pretty well, displaying the marker and background on the monitor, but when trying to print the map, the transparent parts went black.

This is what Google did, now see what it looks like, when you try to print a map on IE6:

I didn't want to look for another workaround for the workaround, so I decided, to create separate files with reduced quality (IE6 supports transparency in 256 color images):

They are not the prettiest, but at least they still look good, when you print the map. All other browsers do get the high-res version.

I also added some nice cursors which make it more fun to use, than the normal pointer.

Cursors

At Google Maps, Bing and Yahoo Maps you can see, that they all use this nice little finger, hand and fist mousecursor in the map, when dragging it and hovering over an UI-element or a marker.

I also tried to implement this cursors, which is quite easy if you only work on one browser. But if you start testing it with another one, you will always find a new situation, that you hadn't considered before and that needs a special workaround.

Therefore I did a lot of testing with events, and this page helped me to understand the difference between capturing and bubbeling phase.

Here is the old version and here the new one.

I wrote a little script, that helps me setting the cursor in dependence of the browser:

// set cursor for an object via css-style
// vendor specific cursors
// or via url
setCursor = function( object, string) {
    // Internet Explorer
    if (navigator.userAgent.indexOf("MSIE") != -1) {	// tested on IE6&8
        if (string == "grab")
            object.style.cursor = "url('./hand.cur'), default";
        else if (string == "grabbing")
            object.style.cursor = "url('./fist.cur'), move";
        else
        object.style.cursor = "pointer";
    }
    // others
    else {
        object.style.cursor = "-moz-" + string;			// tested on firefox 3.6
        if (object.style.cursor != "-moz-" + string) {
            object.style.cursor = "-webkit-" + string;		// tested on safari 5 and chrome 12
            if (object.style.cursor != "-webkit-" + string) {
                object.style.cursor = "-ms-" + string;
                if (object.style.cursor != "-ms-" + string) {		// missing, not sure if it works
                    object.style.cursor = "-khtml-" + string;
                    if (object.style.cursor != "-khtml-" + string) {		// missing, not sure if it works
                        object.style.cursor = string;
                        if (object.style.cursor != string){
                            object.style.cursor = "pointer";
                        }
                    }
                }
            }
        }
    }
};

The cursor files for the Internet Explorer, I created with the help of the screenzoom on my mac and a little software called JustCursors.

So far I successfully tested the cursors on Firefox 3.6, Safari 5 and Chrome 12. IE6 and IE8 still have some small bugs, that I am working on.

Other browser are still to be tested. If you find any bugs, please tell me!

Update 4: July 14th

This week I improved the cursors I implemented last week and I also implemented a first infobox based on HTML5 into khtml.maplib. With this progress I think I can say that have caught up with the original timeplan.

Cursors

I did some more improvement on the cursor-code and successfully tested it on IE6 & IE8.

Therefore I had to do a little workaround for the standardmarker, because IE has troubles with the shape area.

I also took out the shape area for touch devices (tested in iPhone 4 and iPad 1 so far), to make the markers better grabbable with the finger.

You can test it: here

Infobox

For the infobox, I did a lot of research again, how the others do it (click on the marker to get the infobox):

Google has again by far the most complicated approach, breaking their infowindow in more than 20 divs styling it with sprites and a nice shadow. But their infowindow also has the most aesthetics compared to the others.

My first approach to the infobox is using HTML5. Of course I am aware that it will not work on older browsers, but I want to concentrate on the core-functionality first and try to improve it later.

The pointer and the close-cross are embedded images again to save http-requests (again this will not work on older browsers, but I will deal with that later):

The rest of the infobox is done with a div with round-corners.

One special thing about the infobox is, that it can be opened on any object on the map, not only markers. Therefore the object only has to provide a position property and maybe a pixelOffset for this position.

An infobox can also be attached to a position without any object.

This works pretty nice as you can see here (click on a marker to open the according infobox).

This was pretty easy for desktop-browsers, but I was facing some problems on touch devices:

The infobox could not be opened, because the click-event was suppressed by the map. So I had to do a manual click-detection with touchstart- and touchend-events.
The close-cross was too small to be touched with a finger, so I had to display it larger on touch-devices.

So you can see it is working, but there are still improvements to make:

graphics for non-HTML5 browsers
create a shadow for infobox
re-centering map when opening infobox
rendering of infobox when moving marker with opened box
prevent unwanted opens of infobox

Update 5: July 21nd

This week I added the feature to move the map, when dragging a marker to the edge.

Marker

I was facing some minor troubles with the rendering function of the marker. With the old one, the dragged marker was flickering heavily when the map was moved.

The reason was, that the new pixel-coordinates of the dragged marker were always calculated from the gps-coordinates and that was too slow when the map was moved. So I had to differ in the rendering-function between the marker that is currently dragged and the other ones and do a different calculation for the pixel-coordinates.

Here are the two versions. Grab a marker and drag it to the edge of the map to see the difference.

This was the old version: map is not moving
This is the new version: map is moving

Update 6: July 28th

This week I added the feature to move the map, when an infobox is opened that projects beyond the edge of the map.

Infobox

Here are the two versions. Drag the map so that a markers is near the edge and then click the marker to open the infobox.

This was the old version: map is not moving
This is the new version: map is moving

Update 7: August 4th

This week I worked on the layout of the infobox to make it compatible to non-HTML5 browsers.

Infobox & Markers

Here are the two versions. The first one is a single HTML5-div with border-radius, the second one consists of 9 divs for edges and corners with an embedded graphic to make the infobox good looking on older browsers. I also removed all of the innerHTML-statements for security reasons and replaced them with standard DOM-manipulation.

I also did a rework on the mapmove-function when dragging a marker to an edge due to bad usability test. The map moved to fast, so I changed the function that it does not increment the speed to a fixed value, but that the speed the map moves depends on the distance of the marker to the edge. The nearer you drag it to the edge, the faster the map moves.

This was the old version: infobox with HTML5 border-radius and fixed mapmove-speed
This is the new version: infobox with embedded graphics for corners and mapmove-speed dependent on distance to the edge

These are the embedded images: corners

pointer

and close-button

Update 8: August 11th

I did a lot of more work on the Infobox and on the marker API to make it compatible to the Google API.

I also found out, that I made a mistake saving the PNG-files in photoshop. The "File" - "Save for Web" - command helped me save file size with the embedded images.

Infobox

The size of the infowindow is now calculated according to the content with a maximum of the mapsize and if the content exceeds the mapsize, a scrollbar is added.

See these two sites for comparison:

Google InfoWindow: with large amount of text
and mine: with the same amount of text

also notice the scrolling function and the improvement in the mapmove-function

For more text styling, see these two sites:

Google's simple infowindow example: Mount Uluru (click on the marker!)
and mine: Mount Uluru (click on the marker and compare!)

I also created a shadow for the infobox with an embedded image. This will not work on older browsers, therefore a workaround would be needed.

The shadow is divided onto 9 divs to match the size of the infobox. Each div contains a part of the same image correctly adjusted to look like one image.

shadow:

There are still improvements to be done, to make the infowindow work on older browsers (IE6).

I also made another major achievement this week: The infobox is not opening unwanted any more when dragging a marker and is now also moving with the marker as you drag it!

Check it out here!

Marker

If you look at the source-code, you may notice that they are now pretty much the same. Together with my mentor I decided to use the same parameters to make it easy to port the code from google markers to khtml.maplib. You can now use the code directly from sites like this.

This is what it looks like:

var point = new mr.LatLng(50.875311, 0.351563);

var image = new khtml.maplib.overlay.MarkerImage(
       'marker-images/image.png',        // url to image
       new khtml.maplib.Size(20,20),     // size of the image
       new khtml.maplib.Point(0,0),       // origin in a sprite
       new khtml.maplib.Point(10,20)    // anchorpoint on the map
);
	
var shadow = new khtml.maplib.overlay.MarkerImage(
       'marker-images/shadow.png',      // url to image
       new khtml.maplib.Size(34,20),     // size of the image
       new khtml.maplib.Point(0,0),       // origin in a sprite
       new khtml.maplib.Point(10,20)    // anchorpoint on the map
);
	
var shape = {
       coord: [14,0, 15,1, 16,2, 17,3, 18,4, 19,5, 19,6, 19,7, 19,8, 19,9, 19,10, 19,11, 19,12, 19,13, 19,14, 18,15, 17,16, 16,17, 15,18, 13,19, 5,19, 4,18, 2,17, 2,16, 1,15, 0,14, 0,13, 0,12, 0,11, 0,10, 0,9, 0,8, 0,7, 0,6, 0,5, 1,4, 2,3, 2,2, 4,1, 5,0, 14,0],
       type: 'poly'
};
	
var marker = new khtml.maplib.overlay.Marker2({
       draggable: true,
       raiseOnDrag: true,
       icon: image,
       shadow: shadow,
       shape: shape,
       map: map,
       position: point
});

I also added a function to suppress map-zooming when doubleclicking on a marker or a infowindow.

You can play around with some markers here!

I also wrote a little script to place markers via drag and drop onto a map: check it out here!

Map

Last but not least I added some features to the map:

zooming out with a double rightclick
crosshair cursor when using rect-zoom with shift key pressed
suppress contextmenu when right-clicking on the map

Check out this map!

Final

As a final work, I did the JSdoc for the new classes (Marker and InfoWindow) of the map.

Project Completion

On August 22nd I completed this project successfully.

You can download the whole maplib library with this projects work including API-documentation and examples here

I want to thank OSM for the opportunity taking part in GSoC 2011 and my mentor Bernhard Zwischenbrugger for the support.

Improving khtml.maplib

Contents

Project Ideas

Already existing interface

Improvements

Approach

Prospective Timeline

Actual Timeline

Project Progress

Update 1: May 15th

Research

Preliminary work

Update 2: June 30th

Bugfixes

Update 3: July 7th

Markers

Cursors

Update 4: July 14th

Cursors

Infobox

Update 5: July 21nd

Marker

Update 6: July 28th

Infobox

Update 7: August 4th

Infobox & Markers

Update 8: August 11th

Infobox

Marker

Map

Final

Project Completion

Navigation menu

Improving khtml.maplib

Project Ideas

Already existing interface

Improvements

Approach

Prospective Timeline

Actual Timeline

Project Progress

Update 1: May 15th

Research

Preliminary work

Update 2: June 30th

Bugfixes

Update 3: July 7th

Markers

Cursors

Update 4: July 14th

Cursors

Infobox

Update 5: July 21nd

Marker

Update 6: July 28th

Infobox

Update 7: August 4th

Infobox & Markers

Update 8: August 11th

Infobox

Marker

Map

Final

Project Completion

Navigation menu

Search