<!--

OKAY. Welcome to this overcomplex and somewhat fragile map rendering system, based on WebGL and KML files.

Here's basically how it works. Start from a KML file--I use Google Earth for the most part. You are going
to draw whatever shapes you want in Google Earth, using the "Add Path" tool. These can be:

* Closed paths, for things like islands or the outlines of cities
* Lines, for things like rivers
* Path segments, for where you want to assemble larger polygons out of smaller groups.

For example, say you're building a map of the United States. You might draw the outlines of Wyoming, Colorado
and Utah as their own closed paths. Alternatively, however, you could draw each of the states borders based on
their intersection with other states and have 13 paths:

* The Colorado-Utah border
* The Colorado-Wyoming border
* The Colorado-Nebraska border
* The Colorado-Kansas border
* The Colorado-Oklahoma border
* The Colorado-New Mexico border
* The Wyoming-Nebraska border
* The Wyoming-South Dakota border
* The Wyoming-Montana border
* The Wyoming-Utah border
* The Utah-Idaho border
* The Utah-Nevada border
* The Utah-Arizona border

This way, you will reuse certain paths when building the outlines of the individual states. You can imagine
areas in which a political border might also be the shape of a river, so you could reuse the river path
for the border path.

You can call these paths whatever you want in Google Earth, though they should be named without spaces.

Certain kinds of names are reserved in the rendering engine. All paths beginning with "t" and "d" are used for
terrain contouring, with "t" representing an increase in elevation and "d" representing a decrease in elevation
if there is some area in which the terrain dips, like a valley or a crater. The color of lines is not important,
and neither is the width, again with one exception: "t" or "d" paths with width 2 are treated as being major
elevation shifts. Assume that every contour line represents 100m of elevation change. Every 10 of these, say, 
set the style to be width 2. These are then flagged, so that at high zoom levels the map will only use these
to draw the contour of the terrain.

ANYWAY. DONE DRAWING?

Save the KML file to something like "mymap.kml" and open "latlon_to_js.py". Change the "loc" variable to "mymap"
and then run latlon_to_js.py in the same directory as your KML file. You should get two outputs: mymap_paths.js
and mymap_bb.js. 

These are javascript files that are used by the rendering engine. mymap_paths.js simply contains a list of every
path in the KML file, with an array of geocoordinates. mymap_bb.js contains the bounding boxes (the min and max
geocoordinate for every path) which is used to help the renderer decide which polygons to show based on what
is within the viewport at any one time.

By default, the renderer actually shows nothing. For that, you need a separate definition file. In the example
below, this is "mapdatacs.js", which I use for Cannon Shoals. If you open it, the file is commented and explains
how all the different types of objects are displayed. You can then use this to choose what geopaths are displayed
and how they are styled on the map.

HOW THE RENDERER ACTUALLY WORKS

When you start the renderer, it creates a flat plane in 3D space based on the width and height of the browser
window. The engine then goes through every geographic feature, river, city, etc. and draws them onto an HTML5
canvas object, which is then applied as a texture to the plane. I use WebGL for this for two reasons:

1. It allows me to do animations, which have not yet been re-implemented in this version of the renderer
but can be used for things like showing movement (I use it to show the progression of battles)
2. It allows me to take the terrain definition and use that to fake a sense of depth for the map.

Coordinates are rendered using a normalized Mercator projection based on a somewhat arbitrary zoom level to
define a grid size, which is equal to 2^zoom, so that at zoom level 4 the world is a grid 2^4 squares wide and high.

For n=2^zoom, then for a lon,lat pair the normalized coordinates are:

x = n * (λ+180)/360
y = n * (1-(ln(tan(φ*π/180) + 1/cos(φ*π/180))/π)) / 2;

A NOTE ABOUT LABELING

Labels often collide and they are ugly. This is something I need to work on fixing in the next version of the 
software; most of this comes from my redoing the labels as vector graphics instead of drawing them directly onto
the HTML canvas. In particular, labels that are attached to paths have no collision detection, and my solution
for this is hacky and unfortunate. So. I will work on this.

A NOTE ABOUT CURVES

Geopaths can be defined as smoothed or unsmoothed. If they are unsmoothed, then each path is rendered as:

p1[x,y]
p2[x,y]
p3[x,y]

and so on. If, however, they are rendered as "smooth" then I cheat and draw them as quadratic Bézier curves with
the start point at p1, the CONTROL POINT at p2, and the end point at the midpoint of p1 and p2. This produces a
pleasing curve and keeps me from having to manually decide where to place the curve control points. However, it
also means that a smoothed path DOES NOT END AT ITS LAST POINT. It ends at midpoint of its last TWO points.

This is only really an issue if you are drawing, for example, road interactions or river junctions, where you might
otherwise be surprised by the fact that the two do not appear to join up when you expect them to.

Mathematically, I am--to be blunt--not smart enough to figure out a better way of doing this. Sorry.

KNOWN ISSUES

haha

20190818 known issue list:
* No collision detection for labels flowed onto paths
* Resizing the browser window does not resize the webGL viewport until the whole page is refreshed
* In mobile browsers, does not take POI options into account when determining the height of the options panel
* Animations almost certainly do not work
* Custom typefaces may not load properly
* All graphics are badly optimized (see note)

FIXED ISSUES:
"* Undocumented feature: "Overlays""
"* The map is blurry at certain aspect ratios and viewport sizes"

ABOUT THAT OPTIMIZATION

The loading process goes like this:
- Get the viewport width and height
- Create an HTML5 canvas that is the smallest power of 2 larger than twice the width and height
- Create a webGL plane that is larger than the viewport

When you drag with the mouse, you're actually moving the webGL plane. If you scroll too far, then the canvas is 
redrawn and the plane is moved back to the origin. I double the width and height to allow you to scroll sufficiently
far in either direction without seeing artifacts.

The power of 2 is necessary because webGL requires textures to be powers of 2. However, this means that the texture is 
often something like 4096x4096 pixels, which is huge and no doubt consumes an absurd amount of memory. Also, in choosing
whether or not to render a polygon, I check to see whether ANY part of that polygon is in ANY part of the viewport
so there are many cases in which you PROBABLY won't see a geopath but I choose to render it anyway.

If smooth contouring is turned on, then there is an additional step of building the height map, blurring it, and then
applying that to the mesh. This means that render times can range from 50ms to nearly a second depending on how much
is on the screen and what you're doing with it. It's a little less than ideal, but I don't know how to fix it
without a complete refactor of everything.

-->

<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<meta name="viewport" content="width=device-width" />
		<!--<meta name="viewport" content="initial-scale=1.0, width=device-width" />-->
		

		<!--
			These are basically unused right now,
			but the map might break if they're not included
		-->
		<script src="./scripts/animfunctions.js"></script>
		
		<!--
			These are always needed; don't change them.
		-->
		<script src="./scripts/jquery-3.2.1.min.js"></script>
		<script src="./scripts/Tween.js"></script>
		<script src="./scripts/three.js"></script>
		<script src="./scripts/velocity.min.js"></script>
		<script src="./scripts/FastBlur.js"></script>
		<script src="./scripts/common.js"></script>
		<script src="./scripts/mapfunctions.js"></script>


		<!--
			These are the three files that define everything
			about the map. Basically just change these.
		-->
		<script src="./scripts/mapdatakashkin.js"></script>
		<script src="./kashkin_paths.js"></script>
		<script src="./kashkin_bb.js"></script>
		
		<link rel="stylesheet" type="text/css" href="map.css">
	
	</head>
	
	<body onload="setup()">
		<div class="container" id="mapcont">
			<div class="render" id="render3"></div>
			<div class="caption" id="caption"></div>
			<div class="replay_control" id="replay_control">
				<span class="replay_next" id="replay_next" onclick="replay_next()">Next</span>
				<span class="replay_cancel" id="replay_show" onclick="replay_stop()">Stop</span>
			</div>
			<svg class="labels" id="labels" width="4096" height="2048"></svg>
			<canvas class="map" id="map" width="2048" height="2048"></canvas>
			<canvas class="map" id="normal" width="1024" height="1024"></canvas>
			<canvas class="map" id="normal_river" width="2048" height="2048"></canvas>
			<svg class="svglayer" id="svglayer" width="4096" height="2048"></svg>
			
			<canvas class="map" id="infobox" width="512" height="256"></canvas>
			<div class="controls">
				<div id="plot" onclick="plot()">Plot</div>
				<div id="log" onclick="log()">Log</div>
				<div id="logresults">data</div>
			</div>
			<div class="legend" id="legend">
				<div class="opt_header" id="opt_header" onclick="map_option_cycle()">Options (show)</div>
				<div class="map_options" id="map_options" ></div>
				<span class="z_left" onclick="map_zoom('o')">-</span><span class="z_right" onclick="map_zoom('i')">+</span>
			</div>
			<div class="mapkey" id="mapkey">
			</div>
			<div class="scale" id="scale">1.0 km</div>
			
		</div>
		<div class="debuginfo" id="debuginfo"></div>
	</body>
</html>