Skip to content

Commit

Permalink
Alpha 3 docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Ryan committed Sep 20, 2011
1 parent 45d9d3d commit d85860d
Show file tree
Hide file tree
Showing 25 changed files with 532 additions and 103 deletions.
11 changes: 8 additions & 3 deletions README
Expand Up @@ -11,8 +11,13 @@ Documentation is hosted at http://host.appgeo.com/libs/geo/
=== Version alpha3 ===
* docs - geomap - more modes: zoom, drawPoint, drawLineString, drawPolygon
* geomap - [bug] tiles do not show when pixel sizes are near or lower than 1.0
* geo - cache bbox as geoBbox to match namespacing convention started by jQuery Mobile
* docs - geo - initial geometry operations: bbox, distance, contains, centroid
* docs - geomap - shape event
* docs - geomap - refresh argument in append, remove & empty
* docs - geomap - document the resize method

=== Version alpha2.5 ===
=== 1.0a2.5 (2011-08-03) ===
* geomap - find - [bug] does not handle GeoJSON features
* geomap - find - allow for 0 pixel tolerance
* geomap - find - check for bbox on non-Point geometries before getting too specific
Expand All @@ -27,7 +32,7 @@ Documentation is hosted at http://host.appgeo.com/libs/geo/
* docs/geomap - scale map according to cursor location instead of re-centering during double-click zoom
* geomap - iOS - [bug] second tap can be anywhere & cause a zoom

=== Version alpha2 ===
=== 1.0a2 (2011-06-29) ===
* geomap - Support dynamic map services
* geomap - [BUG] geomap causes a script error if jQuery UI is already included
* docs - Document shape methods
Expand All @@ -49,7 +54,7 @@ Documentation is hosted at http://host.appgeo.com/libs/geo/
* geomap - [bug] GeometryCollection shapes do not draw with their parent shape's style
* geomap - implement empty method

=== Version alpha1 (2011-05-09) ===
=== 1.0a1 (2011-05-09) ===
* docs - Document a new interface to our internal map control
* geomap - Port interactive map widget base to jQuery UI widget factory
* geomap - Support tiled map services
Binary file added apple-touch-icon.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
70 changes: 60 additions & 10 deletions dev-journal-ryan.txt
@@ -1,20 +1,21 @@
== to do ==

=== alpha3 ===
* docs - geo - initial geometry operations: bbox, distance, contains, centroid
* docs - geomap - shape event
* docs - geomap - use name instead of id for service objects
* docs - geomap - refresh argument in append, remove & empty
* docs - geomap - document the resize method
=== 1.0a3 ===
* geo - make initial geometry functions public
* geo - [internal] add an internal ignoreProj argument to $.geo geometry functions.
* [internal] - geo - add an internal ignoreProj argument to $.geo geometry functions.
* geomap - make the refresh argument in append public, add one to remove & empty
* geomap - append should remove the shape's bbox cache
* geomap - remove should remove the shape's bbox cache
* geomap - empty should remove the bbox cache for all shapes
* geomap - ? append should remove the shape's bbox cache (it will be recalculated later)
* geomap - [bug] adding a service by modifying the services array after initialization fails
* geomap - [bug] multiple maps do not work on the same page
* [internal] - geo - add private _from/_toGeodeticBbox methods
* geo - calculate & cache bbox in projected coordinates
* geo - cache point bbox if $.geo.proj is not null
* geo - cache only with append/remove, not in all bbox calls
* geo - use Array.push instead of $.merge
* geo - prefer GeoJSON object over $.data, assume it's accurate
* geo - [internal] add private _from/_toGeodeticBbox methods
* docs - launch jquerygeo.com

=== future ===
* docs - geomap - more modes: measureDistance, measureArea
Expand All @@ -26,6 +27,8 @@
* docs - explain the 96px scale bar, why 96?
* docs - write a full page about GeoJSON and what each object type is to $.geo
* docs - proj - mention that *Geodetic methods can also do bbox
* docs - geomap - allow name as well as id for service objects
** if a service has a name property, it will maintain a hidden input with the given name
* docs - geomap - service-level shapes
* geomap - service-level shapes
* geomap - deep extend existing service objects when services property is set
Expand All @@ -37,6 +40,7 @@
* geo - implement $.geo.centroid
** JTS note: "The centroid is equal to the centroid of the set of component Geometries of highest dimension (since the lower-dimension geometries contribute zero "weight" to the centroid)"
* geo - Support WKT with $.geo.parseWKT & $.geo.textify
* geo - All bbox operations should be done in non-geodetic coordinates for accuracy
* geomap - [bug] mouse wheel on bad or missing tile doesn't zoom out on first rotate
* geomap - service divs should have class="geo-service"
* docs/geomap - store WKT input for each service
Expand All @@ -49,9 +53,55 @@
* graphics - See Modernizr for comment on BB Storm & canvas detection
* geographics - Document graphics widget
* geomap - [BUG] Android browser stops pan/zoom after 7 logos on logo demo
* geomap - design how to store shapes as a hidden input
* geomap - store a copy of shapes as WKT in a hidden input
* geomap - only update WKT copy if shape is appended with refresh argument set to true
* geomap - find - [maybe] after flatten, check more cached bboxes for non-Point geometries

==2011-09-20==
===cache===
I may be caching too aggressively. I think I should remove caching from $.geo.bbox and instead cache inside of append and clear the bbox cache in remove. I really only need it in the find method.

==2011-09-18==
===shape===
Working on the event docs.

===name===
I was originally going to rename id in the service objects to name so I could use it as an input name on a hidden input. However, I'm now going to require id but allow name as an optional property. If present, it will create the hidden input. This is now a future task and will not be in alpha.

===append===
While adding the refresh argument to append, I started thinking again how I want to implement service-level graphics. It would be very nice if I could have the map>service syntax to jQuery and call append, remove and empty on that. I think I defined the syntax a while ago...yeah, see "On shape functions" from 2011-06-02.

The issue I have is that a page can have two maps. The default service has id=OSM. So, if I allowed $("#map #OSM") syntax, it would cause the page to have two elements with the same id, #OSM. However, $("#map [data-geo-service='OSM']") is way to wordy. I'll have to discuss this with others later as this is not an alpha feature either.

==2011-09-16==
===foss4g===
FOSS4G is an inspiring conference. I gave my talk and people seemed interested. There was a question about Google. I answered that it's illegal to use them and Chris Schmidt mentioned on Twitter that it's not illegal, it's just hard. We're talking different things. jQuery Geo would use Google tiles directly, which is against license. We will never host a third party widget inside the jQuery Geo div as part of the core functionality. OpenLayers wraps the official Google widget to get around the license restriction (since it's the official Google widget, there's nothing wrong with it) & keeps it up to date (or slides it around) when the user interacts with the OL map. I might do something similar as a blog post when I open up the service types plugin system but until then, but it won't be part of jQuery Geo..."here's how to do it if you want", type of thing. The developer would have to pull in the Google maps API themselves.

===centroid===
I'll have to see if JTS uses Point or Coordinate as a return value & match it.

Centroid needs to use $.geo.proj for accuracy. The centroid should be calculated in web mercator & projected back to geodetic.

===proj===
The way we do projection is different than how GIS does it. Usually, when you define a projection, you work in non-geodetic coordinates because the coords have been projected to a flat plane. With jQuery Geo, you work in projected coordinates (I call them non-geodetic) when you set $.geo.proj to null. This can be a little confusing but I think it works.

The first thing we would have to do internally is set $.geo.proj to null because we use pro

===bbox proj===
bbox might be an issue. a bbox in geodetic coordinates (lon/lat) that is a rectangle, will not be a rectangle in web mercator. That's not a problem with setting the bbox property on geomap but could prove interesting for the bbox of geometry objects. For example, the bbox of a square polygon will not be a parallelagram in geodetic coordinates.

SUGGESTION: Calculate & cache bbox in projected coordinates
SUGGESTION: Document that lon/lat bboxes will not appear to be correct?

===bbox cache===
Peter and I got into a talk about caching bboxes. He's worried that we will have too many floating references to objects that cannot be collected. That is a valid point. For example: a user creates a polygon as an object literal, they then call $.geo.bbox on it, then the function ends. We will have a cache of the bbox, but most importantly the cache will reference the original polygon so the browser cannot remove it from memory. I agree that this isn't a great situation. However, the performance benefit gained by the find method is hard to ignore. Also, this only becomes a problem when the developer calls bbox directly. Even though we call it during the find method (building up cache), they are all removed when the dev removes shapes from the map with the remove method. I also know I need to research more about how $.data works with objects. I may be wrong about the reference/memory leaks.

===point bbox cache===
Now that I know I should cache bbox as non-geodetic, I think I should revisit my jsperf regarding caching a point. Since there's going to be much more calculation involved in $.geo.bbox, I might want to cache points. However, I think I should only cache them if $.geo.proj is not null. When it's null, non-cached points will still be faster as per my original jsperf test.

===events===
The new shape event will need a new event type. Position event won't cover it but it's similar. I'm not 100% sure if I should merge them. The new event type will be a shape event.

==2011-08-24==
===utah===
While zooming in, Chrome skips zoom level 12. I wonder if that's a bug in the control. It is. It's a rounding error in _getTiledZoom. Using floor and * instead...fixed.
Expand Down
2 changes: 1 addition & 1 deletion docs/examples/css/style.css
Expand Up @@ -24,7 +24,7 @@
max-width: 45%;
opacity: .8;
padding: 8px;
position: absolute;
position: absolute !important;
right: 16px;
top: 16px;
}
178 changes: 178 additions & 0 deletions docs/examples/hurricane.html
@@ -0,0 +1,178 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">

<title>hurricane</title>
<meta name="viewport" content="width=device-width, minimum-scale=1, maximum-scale=1">

<meta name="description" content="Displaying storm activity in the Atlantic">
<meta name="author" content="Ryan Westphal">
<link rel="stylesheet" type="text/css" href="css/style.css" />
<style type="text/css">
#map
{
position: fixed;
bottom: 0;
left: 0;
right: 0;
top: 0;
}
#popup
{
background: #fff;
border: solid 1px #444;
border-radius: 8px;
display: none;
padding: 4px;
position: absolute;
opacity: .6;
overflow: hidden;
width: auto;
}
</style>
</head>
<body>
<div id="hurricane">
<div id="map" style="position: fixed; left: 0; top: 0; right: 0; bottom: 0;">
<div class="info">
<a href="../" class="docLink">&lt; docs</a>
<h1>Hurricane tracking</h1>
<p>Displaying a snapshot of storm data extracted from <a href="http://stormpulse.com">stormpulse.com</a></p>
</div>
<div id="popup">
</div>
</div>
</div>
<script id="tmplHurricane" type="text/x-jquery-tmpl">
<h2>${category}</h2>
<table>
<tr><th>date</th><td>${date}</td></tr>
<tr><th>accuracy</th><td>${accuracy}/40</td></tr>
<tr><th>eye diameter</th><td>${eyeDiameter}</td></tr>
<tr><th>direction</th><td>{{if direction}}${direction}&deg;{{/if}}</td></tr>
<tr><th>pressure</th><td>${pressure}</td></tr>
<tr><th>wind radii</th><td>${windRadii}</td></tr>
<tr><th>wind speed</th><td>${windSpeed}</td></tr>
<tr><th>gusts</th><td>${gusts}</td></tr>
</table>
</script>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
<script src="http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.min.js"></script>
<script src="http://host.appgeo.com/libs/geo/test/jquery-geo-test.min.js"></script>
<script>
$(function () {
$("#tmplHurricane").template("hurricane");

var map = $("#map").geomap({
center: [-76.6, 30.4],
zoom: 5,
move: function (e, geo) {
$("#popup").hide().html("");
var tracks = map.geomap("find", geo, 4);

$.each(tracks, function() {
if (this.type == "Feature") {
$.tmpl("hurricane", this.properties).appendTo("#popup");
$("#popup").css({
left: e.pageX,
top: e.pageY
}).css("display", "inline-block");
}
});
}
});

$.ajax({
url: "http://host.appgeo.com/libs/geo/data/hurricane.txt",
dataType: "json",
success: function (result) {
var shapeStyle = {
color: "gray",
strokeWidth: "4px"
};

$.each(result.stormData.storms.tracks[0].track, function(i) {
var trackPoint = {
type: "Feature",
geometry: {
type: "Point",
coordinates: [
parseFloat(this[16]),
parseFloat(this[7])
]
},
properties: {
eyeDiameter: this[0],
windRadii: this[1],
category: this[4],
accuracy: this[10] || 0,
direction: this[11],
pressure: this[14],
date: this[15],
gusts: this[17],
windSpeed: this[18]
}
};

//console.log("accuracy: " + trackPoint.properties.accuracy);
if (trackPoint.properties.date != null) {
var dateStr = trackPoint.properties.date.toString(),
year = dateStr.substr(0, 4),
month = dateStr.substr(4, 2),
day = dateStr.substr(6);
trackPoint.properties.date = year + "-" + month + "-" + day;
}

switch (trackPoint.properties.category) {
case "Tropical Storm":
shapeStyle.color = "#eee";
break;

case "Hurricane - Category 1":
shapeStyle.color = "#ff8";
break;

case "Hurricane - Category 2":
shapeStyle.color = "orange";
break;

case "Major Hurricane - Category 3":
shapeStyle.color = "#f88";
break;

default:
shapeStyle.color = "gray";
break;
}

if (trackPoint.properties.accuracy != null) {
var pos = trackPoint.geometry.coordinates,
a = .2 + (40 - trackPoint.properties.accuracy)/40;

shapeStyle.strokeOpacity = trackPoint.properties.accuracy/40;

map.geomap("append", {
type: "Polygon",
coordinates: [[
[pos[0] - a, pos[1] - a],
[pos[0] - a, pos[1] + a],
[pos[0] + a, pos[1] + a],
[pos[0] + a, pos[1] - a],
[pos[0] - a, pos[1] - a]
]]
}, $.extend({}, shapeStyle));
}

map.geomap("append", trackPoint, { color: "#444" });
});
},
error: function (xhr) {
alert("Sorry, we were unable to read the storm data.");
}
});
});
</script>
</body>
</html>

14 changes: 6 additions & 8 deletions docs/geo/bbox.html
Expand Up @@ -48,14 +48,12 @@ <h1>bbox</h1>
delete shape.bbox;
var calculatedBbox = $.geo.bbox(shape);
</code></pre>
<p>When $.geo does calculate a bbox, it will cache the result for faster access next time. Continuing from the above code, the next time we call bbox we will get the cached value.</p>
<pre><code><span class="comment">// a calculated bbox is cached by $.geo,</span>
<span class="comment">// but the property will not be automatically added</span>
<span class="comment">// back to the shape object ($.geo doesn't modify your objects)</span>
var cachedBbox = $.geo.bbox(shape);</pre></code>
<p>Keep this in mind for the uncommon situation where you want to change an object's specific coordinates directly (or geometries if you're working with the bbox of a GeometryCollection) rather than replace the whole object. In this case, you should remove the cached bbox. $.geo caches the bbox using jQuery's data function under the name geoBbox. To remove this cache, you can call removeData directly on the shape object:</p>
<pre><code>$.removeData(shape, &quot;geoBbox&quot;);</code></pre>
<p>$.geo.bbox is projection agnostic which means it never calls the from/toGeodetic methods in $.geo.proj as the algorithm is the same regardless. The return bbox will be in the same units as your shape argument.</p>
<p>To calculate an accurate bbox, this method must operate in non-geodetic coordinates.
Therefore, if $.geo.proj is not null, this method first calls fromGeodetic on the incoming shape and toGeodetic on the positions in the returned bbox.</p>
<p>Due to the liberties taken by web mercator to display a round Earth on a single
flat plane, when working in geodetic (lon/lat) coordinates, the result of the
$.geo.bbox function may not be exactly what you expect based on your input
geodetic geometry.</p>
<p>This function is similar to Geometry.getEnvelope in JTS.</p>
</div>
</div> <!-- end of #container -->
Expand Down

0 comments on commit d85860d

Please sign in to comment.