Public Lab Research note

  • 4

MapKnitter Annotations: Interface Refactoring

by justinmanley |


I am working to add rich annotation functionality to MapKnitter as part of Google Summer of Code (read about my project here: This is my seventh week of coding.

If you're interested in reading about Leaflet.Illustrate, the Leaflet plugin that I wrote over the past few weeks to power MapKnitter's annotations, you can check out my last research note.

The goal of this research note is to post some of my ideas for refactoring the MapKnitter interface to expose annotation functionality and solicit feedback from the community.

Areas for Improvement

The MapKnitter interface currently looks like this:


I think that there are several areas for improvement with this interface:

  • I love the way that the MapKnitter homepage presents a selection of recent maps. I think this is an awesome way to hook people in and communicate what MapKnitter is about. However, once a user clicks on a map, they are taken to an overview page for the map, not the map itself. Often, this overview doesn't even show the map itself.

  • It is clear to me from looking through the archives that users seldom use the "description" field when creating a map. Furthermore, right now, the "description" field is worse than useless because most are populated by spam text.

  • Export functionality is scattered all over: right now, there are no fewer than three places on the overview page to export the map.

  • The overview page doesn't make it easy to view or edit the map metadata (such as the base satellite layer), description, place, or image metadata.


Ideas for Improvements

It may not be possible to eliminate the overview page entirely, but I would like to move as much functionality as possible into the map editing interface so that the full-screen, full-functionality view of the map is the main destination for all users. This full-screen view of the map should be a self-explaining, self-documenting view of the map.

Some sketches:





I built a preliminary implementation of the interface I sketched above. It's in the annotations-interface branch of my fork of mapknitter - controllers and views are called map2.



Let me know what you think about taking the MapKnitter interface in this direction. Obviously there's a lot more that needs to be built in to provide full-featured annotation functionality - but what do you think of combining the overview and editing pages and the split-screen editing page?

balloon-mapping mapknitter software gsoc gsoc-2014


This is super exciting! I have experienced some of these issues when trying to explain how to use mapknitter. So I totally agree with your observations and think you should fix ALL THE THINGS!!!!!!!!!!!!!!

This looks like a really good upgrade. Mapknitter would become really user-friendly if we can do this.

This is so great. Yes, current MapKnitter is a Frankenstein of many changes and revisions over the years. Sweep it clean and make it better!

One note -- we decided at one point to direct people by default to the "viewing" page which has space for narrative and stats and authorship info, etc. rather than dumping them right into the "editing" page where they're immediately given the ability to edit the map and sometimes don't know that they're messing with other peoples' data. But there could easily be another way to warn people or tell them that they are actually editing. And someday we'll have complete edit history and can simply revert changes if people mess things up. We could also ask people if they'd like to revert all the changes they've made in the session, if they try to close the window (maybe). But edit history may be outside scope for your project :-)

Agree with Anish's comment!

Also, if you merge your branch in and give people an alternate "beta" interface, we can compare them directly, by using

/maps/foo (current version) and /map/beta/foo (yours)

and indicate such options in the interface. As scattered as the current version is, we don't want to replace it without being sure we replicate all its features and debug, and having both running simultaneously is a great way to ease into the switch.

are you planning to make annotations editable?

Is this a question? Click here to post it to the Questions page.

Jeff - I have given some thought to edit history. I think that will be a somewhat substantial upgrade, so it may be outside the scope of my project (although I may post a research note soon w/ some of my thoughts on implementing this). I think something that will mitigate the phenomenon of inexperienced users messing up maps that others have made is simply by providing a range of map editing permissions.

This should be simpler to implement than complete edit history - just allow users to set the permissions for each map that they create to 'self' (only the owner can edit), 'everyone', or 'whitelist', to only allow users specified by the owner to edit the map. We can decide what the default should be.

I don't think that interjecting an additional screen does much to protect carefully constructed maps from careless interference. As a casual user, I have been worried more than once when I clicked to open a recently created map, dragged the corner handles around a bit, and then noticed (to my chagrin) that the map had been automatically saved.

I have been developing the new interface with separate controller, model, and views accessible via a /beta prefix to the URL as you suggested. Once I finish the database migrations to add support for new fields, I will submit a PR to allow folks to beta-test.

Liz - I think that any user should be able to annotate a map, regardless of what the editing permissions are on the map. This includes modifying and/or deleting existing annotations. Is this what you mean by editable?

Is this a question? Click here to post it to the Questions page.

Ah, that hasn't been in line with previous ideas about annotation permissions. We don't want carefully added annotations to be deletable. Based on my most recent event, people spend a lot of time typing up their knowledge and uploading photos into the infowindows. It would be bad if anyone could just delete that. Currently, anyone can add annotations to a map, but only the person who has added a given annotation can delete it. I think the owner should be able to delete all annotations as part of managing their map.

My question was more like, "once a map owner has added annotations, can they go in and edit it?" Currently, if you want to change an annotation, there's no was to do it, just have to delete and start over with a new annotation.

Is this a question? Click here to post it to the Questions page.

protect carefully constructed maps from careless interference

agreed - it was a relatively crude way to do this and there are better means, for sure. It was also, however, a sort of "first step" towareds creating a clean Leaflet-based version. But mostly it was just the result of many iterative changes over a long period of time without a 'master plan' - and I encourage you to change it!

re: edit history, an edit history can be a more permissive environment, the idea being that maps are default-editable, unless there's a strong reason to close them off. Edit history can make that sustainable rather than limiting access/permissions from the outset. I do think there is a rudimentary edit lock feature and there is value in a better version of that too, but I'd be reluctant for it to be the default.

awesome re: /beta

also, in keeping with the shift towards simply showing everything and not culling by map_id, author-based permissions on a per-image basis and per-annotation basis would be preferable to map-based permissions. Currently annotations don't 'belong to' a map, actually, which was the first step towards that paradigm. Eventually we'd like it if the moment you select a set of annotations or images is at export time, not from the outset. Maps would become more like "views" to one giant shared map, which is really sorted via location and perhaps time (like, we could have options to show only images/annotations you created, or that were made in a given time period). But that's also kind of a bigger project, so I wouldn't worry too much about it now.

Liz - I see. Sure, I can make annotations deletable only by their owners. Ultimately, though, I really think that annotations should be just as freely editable as map images - I think that annotations should be treated like a visual wiki. How do we handle annotations going out of date or becoming inaccurate over time? Especially in areas where Public Lab is very active, the map view will become very cluttered over a period of several years if annotations can only be added, not removed or hidden. We can make annotations more edit-proof by adding editing history for annotations. This should be a lot easier IMO than for images because there's already a compact JSON representation of annotations (GeoJSON).

Jeff - AHHHH I see. I didn't realize that was the direction that you folks wanted to take with MapKnitter. Makes a lot of sense. I'll keep that in mind as I'm implementing this next stage of changes to make it compatible with the new viewing paradigm as much as possible.

Will also post re: edit history for images soon, if not today, then over the weekend. I agree that edit history is much more powerful than permissions.

Is this a question? Click here to post it to the Questions page.

I think (hope) Jeff is describing something like this:

I make a map by carefully aligning photos, writing a description, and annotating it. I save that view, and whenever I return I can see that view of my map. Anybody else can see that view, and they can also tweak my image alignment, edit my description, and/or make their own annotations and save that new view. Now everybody can see and edit two views of the map. But those two views will never change unless edited or deleted by the person who saved them.

A harder question might be, Can anybody add new aerial photos to a map to extend or improve it? Only the original map maker should be able to delete aerial photos, so probably only the original maker should be able to add more. If you want to add more, start over with a new map.

Is this a question? Click here to post it to the Questions page.

Hmmmm. That's not at all what I had understood from Jeff's comments.

Jeff? Could you clarify?

Is this a question? Click here to post it to the Questions page.

Yeah that's pretty much it -- and if you don't want what other people have added to a given area (an area you're working in, say) you can display only your own additions, and perhaps time-bound them as well. This model prefers filtering out stuff you don't want, as well as revision and recovery, over deletion.

The part that would "never change" is the export. That's where you make a selection of images and annotations, and save them. I think each "view" could generate a number of exports -- say, a timeseries, or before/after. But in assembling your export, you could see others' additions if you like.

I know this is a bit of a different model, but it would solve a lot of issues with having to duplicate maps, etc. -- and also would allow for easier comparison and interaction between what we now call different maps. It'd also give more control in selecting a set of images for export.

Justin - what do you think about, on the edit page, making the images just a little harder to mess with -- say, you have to double click them, or click once and click on the "edit" button or something -- so that by default, you are just panning around the map?

Is this a question? Click here to post it to the Questions page.

Oh sorry, Justin - do you mean the part about

But those two views will never change unless edited or deleted by the person who saved them.

For that, I think I agree with chris's description if in that context "view" is an export. But if we do things by image-ownership rather than map-ownership, maybe it doesn't matter as much? What about if one person uploads a bunch of images and asks others to help them place them properly? The "anyone can edit" system works well for that. Edit history (again, out of scope for your work) would make that less risky for the uploader.

Is this a question? Click here to post it to the Questions page.

I really dig the sidebar concept, full screen map, and loading straight to the edit screen!

I agree with Liz, this differs from a Wiki in the crucial respect that we are seeking to display mostly local knowledge of the map-- not every internet user is therefore of equal standing in regards to edits. The "locked, open, or whitelist" options seem to solve this issue.

@warren We might want to make the edit functions all load locked by default, not permission locked, just edit locked, and unlockable with a simple one-click toggle. Especially on older computers it can be easy to click and drag something accidentally while trying to scroll through. We don't want the interface to be a scary place of accidental changes for casual viewers. The current mapknitter is such a place.

THoughts on handling multiple editors-- What about a "fork" and "overlay" options-- I, the original mapmaker, make a map, and unless I set open permissions or whitelist other contributors, someone else would have to fork my map to add their own changes, or maybe just fork the annotations. We could then list the annotation forks and give the option of switching between them or adding them. Only the original author or whitelist editors could pull forks back to the default layer. I'm not sure if this would get messy in implementation or lead to doubled annotations.

ooh yeah, lock by default is nice. Basically an extra interaction to put the image in edit mode would be great.

How to address Chris's concerns on imagery adding/editing/sharing seems like a tough nut to crack.

Is there any way to overlay different mapknitter photo sets? each map would then be its own thing, but there'd be a "supermap" of the different photo sets for the same site that could be loaded up. This would solve the imagery issue, at the risk of creating a giant annotations headache-- what happens when someone annotates two overlayed maps?

Is this a question? Click here to post it to the Questions page.

It seems like everyone is not on the same page re: Jeff's vision for the future of MapKnitter. Mathew: as I understand it , Jeff is proposing that, in the future, the default view should be a "supermap" (your words) of all of the photo sets for a given location.

It seems to me that, over time, this "supermap" is going to become extremely cluttered. I think that one way of solving this (and perhaps also solving the annotations headache that Mathew mentioned) is to only show the past year (or past six or nine or three months) of images and annotations, and allow the user to view a different time span via a slider that they can scrub back and forth.

I was going to post about map image edit history in a separate research note, but I think it would be better to continue the conversation here:

I'm not sure how uploaded images are stored now, but I think that, in order to enable full-featured editing history (including the ability to rollback arbitrary sequences of changes), an ideal setup would be:

  • Store all images on the server at the time that they are uploaded
  • Represent all transformations to the images in a compact JSON object
  • Each time a change is made, push a new JSON object into the database.
  • When a user requests a map, send them the raw images AND the most recent JSON for each image and apply the transformations in the browser, on the client-side.

This means that, to rollback changes, all we would need to do is retrieve the appropriate JSON entry and push it to the database.

Finally: Regarding Jeff's idea that the default view should be a "supermap" with all image sets around a given area. I think we may want to introduce a slightly modified nomenclature. I propose:

  • Mathew's "supermap" will just be called "the map" - this will have ALL of the uploaded images.
  • What we currently think of as a "map" or "photo set" will be called a "patch". I think this is a much more apt description for what MapKnitter users create, anyway.

Technical note: In order to keep the map running quickly, we'll need to only download images as the user's activity (panning, zooming) brings them into view. But this shouldn't be too hard with Leaflet.

Haha, well, the power's in your hands here, Justin, as nobody else is likely to be coding on MapKnitter :-) -- I've definitely not had time in the past year or two to do much.

Clutter could become an issue, but i like your solution for it, and in some ways we can afford to solve that problem later. What's the opposite of re-arranging deck chairs on the Titanic? Making seat arrangements on the first interstellar starship? I.e. things we can reasonably expect to complete soon all sound good to me, honestly, and we'll figure out the rest when we're closer to having time to implement it.

I like your JSON version history, that's how I'd do it too...

I like your nomenclature of "map" and "patch" -- does "export" still work?

Is this a question? Click here to post it to the Questions page.

I agree with Justin's terminology and view plan. a double slider would be ideal for the history: Screen_Shot_2014-08-08_at_2.45.52_PM.png

in following Jeff's suggestion, I propose that the opposite of "re-arranging the deck chairs on the Titanic" be "building the bridge of the USS Enterprise."

That has a real nice positive ring to it, mathew, thanks :-)

I had actually thought of the Enterprise but was trying to hide my inner nerd. Never again.

The double slider is nice - like Google Earth historical imagery.

All - thanks for a really great conversation about the future of MapKnitter.

Here's how I've decided to proceed for the time being:

  • I am focusing on making the map viewing and editing interface more descriptive, interactive, and social. This includes adding:
    • Public Lab-style tagging and commenting
    • Integration with Public Lab research notes
  • In addition, I am working on merging and integrating the work that other GSoC students (Vidun and Anish) have already done to improve the MapKnitter experience.
  • While I fully support moving the default MapKnitter viewing + editing paradigm to a "supermap"-centric view, rather than a "patch"-centric view, I am not focusing on implementing the "supermap" functionality right now. I feel that this is (potentially) a significant task which is outside of the scope of my project.

I have already added full-featured tagging and commenting to MapKnitter maps and am in the progress of merging and integrating Anish's and Vidun's work - more to come soon in a separate research note.

So excellent! I think it is prudent to integrate and streamline the features already spec'ed and leave supermap functionality for another day.

Justin, this is ambitious and super duper. Thanks and I'm excited to see things progress! Commenting has been a need for some time, but do consider that if we make "publishing a note to" an integral part of the process, i mean really push people to do so, then commenting would be built in. That's not to say it's the only approach, but could work. You know you can set up a draft with parameters: is the post body

That could help in integration perhaps.

I agree supermap is a really big topic and outside the scope. We also don't need to decide all of that right now.

Keep up the great work and check out Anish's work!

Is this a question? Click here to post it to the Questions page.

You must be logged in to comment.