improved global mapping and added documentation