-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
155 lines (108 loc) · 5.02 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
NAME
GeoDNA - Encode latitude and longitude in a useful string format
There's an interactive demo of this at
http://www.geodna.org/docs/google-maps.html
SYNOPSIS
<script type="text/javascript" src="geodna.js"></script>
var geo = GeoDNA.encode( -41.288889, 174.777222, { precision: 22 } );
console.log( geo );
> etctttagatagtgacagtcta
var coords = GeoDNA.decode( geo );
console.log( coords[0], coords[1] );
> -41.288889, 174.777222
VERSION
0.04
FEATURES
* Simple API
Generally you just convert coordinates back and forth with simple
function calls.
* Fast
It's just basic space partitioning, really.
DESCRIPTION
This is a javascript version of the Python "geoprint" system that we developed
a few years back at Action Without Borders.
Its purpose is to encode a latitude/longitude pair in a string format
that can be used in text databases to locate items by proximity. For
example, if Wellington, New Zealand has the GeoDNA(10) value of
etctttagat
(which it does), then you can chop characters off the end of that to
expand the area around Wellington. You can easily tell if items are
close together because (for the most part) their GeoDNA will have the
same prefix. For example, Palmerston North, New Zealand, has a
GeoDNA(10) code of
etctttaatc
which has the same initial 7 characters.
The original implementation of this in Python was by Michel Pelletier.
This uses a concept that is very similar to Gustavo Niemeyer's geohash
system ( http://geohash.org ), but encodes the latitude and longitude in
a way that is more conducive to stem-based searching (which is probably
the most common use of these hashing systems).
FUNCTIONS
GeoDNA.encode
var code = GeoDNA.encode( latitude, longitude, options );
Returns a GeoDNA code (which is a string) for latitude, longitude.
Possible options are:
radians : true/false
A true value means the latitude and longitude are in radians.
precision : Integer (defaults to 22)
number of characters in the GeoDNA code. Note that any more than
22 chars and you're kinda splitting hairs.
GeoDNA.decode
var coords = GeoDNA.decode( code, options )
Returns the latitude and longitude encoded within a GeoDNA code.
radians : true/false
If true, the values returned will be in radians.
GeoDNA.neighbours
var neighbours = GeoDNA.neighbours( code );
Returns an array of the 8 GeoDNA codes representing boxes of equal
size around the one represented by code. This is very useful for
proximity searching, because you can generate these GeoDNA codes, and
then using only textual searching (eg. a SQL "LIKE" operator), you can
locate any items within any of those boxes.
The precision (ie. string length) of the GeoDNA codes will be the same
as code.
GeoDNA.neighboursWithinRadius
var neighbours = GeoDNA.neighboursWithinRadius( code, radius, options );
Returns a raw list of GeoDNA codes of a certain size contained within the
radius (specified in kilometres) about the point represented by a
code.
The size of the returned codes will either be specified in options, or
will be the default (11).
precision: N
If this is present, the returned GeoDNA codes will have this size.
GeoDNA.reduce
var neighbours = GeoDNA.reduce( neighbours )
Given an array of GeoDNA codes of arbitrary size (eg. as returned by
the "neighboursWithinRadius" function), this will return the minimal set
of GeoDNA codes (of any sizes) that exactly cover the same area. This is
important because it can massively reduce the number of comparisons you
have to do in order to perform stem-matching, *and* more crucially, if
you *don't* reduce the list, you *can't* perform stem matching.
GeoDNA.boundingBox
var coords = GeoDNA.boundingBox( code );
This returns an array containing two arrays:
[ [ minimum latitude, maximum latitude ],
[ minimum longitude, maximum longitude ],
]
TODO
* Add conveniences to help you with prefix-based searching
At present you have to understand how this geometry works fairly
well in order to get the most out of this module.
* Bulletproofing
It's not particularly well-tested. And there is the boundary-problem
in that two very close-by locations can have radically different
GeoDNA codes if they are on different sides of a partition. This
is not a problem if you use the neighbouring GeoDNA codes of your
reference point to do proximity searching, but if you don't know how
to do that, it will make life hard for you.
BUGS
Please report bugs relevant to `GeoDNA' to <info[at]kyledawkins.com>.
CONTRIBUTING
The github repository is at
git://github.com/quile/geodna-js.git
SEE ALSO
Some other stuff.
AUTHOR
Kyle Dawkins, <info[at]kyledawkins.com>
COPYRIGHT
Copyright 2012 by Kyle Dawkins