README.md 2.92 KB
Newer Older
Matija Obreza's avatar
Matija Obreza committed
1
Geo Tools
Matija Obreza's avatar
Service  
Matija Obreza committed
2
=========
Matija Obreza's avatar
Matija Obreza committed
3

Matija Obreza's avatar
Matija Obreza committed
4
5
6
Executing the default main class without additional arguments renders the program
options:

Matija Obreza's avatar
Matija Obreza committed
7
8
	$ java -jar genesys-geo-tools-0.2-SNAPSHOT.jar 
	Usage: java -Djava.awt.headless=true -jar genesys-geo-tools-0.2-SNAPSHOT.jar country|landorsea [options] <inputFile> <outputFile>
Matija Obreza's avatar
Matija Obreza committed
9
10
11
12
13
14
15
16
17
18
19
	
	Options:
	<inputFile>   File name or - to read CSV from STDIN
	<outputFile>  File name or - to write CSV to STDOUT
	-v            Increase log level.
	-v            Increase log level.
	-csv ',"\'  Set input CSV separator, quote and escape chars
	
	The program writes log messages to STDERR.


Matija Obreza's avatar
Matija Obreza committed
20
## Running LandOrSea ##
Matija Obreza's avatar
Matija Obreza committed
21

Matija Obreza's avatar
Matija Obreza committed
22
23
24
25
26
Prepare a CSV file with columns `DECLATITUDE`, `DECLONGITUDE`. The
program will test the geographic coordinates against the oceans and water data
and report the result in the column `LANDorSEA_check`.

### Obtaining base data
Matija Obreza's avatar
Matija Obreza committed
27

Matija Obreza's avatar
Service  
Matija Obreza committed
28
Download the two "large split polygons" shapefiles in WGS84 projection from:
Matija Obreza's avatar
Matija Obreza committed
29

Matija Obreza's avatar
Service  
Matija Obreza committed
30
31
32
33
34
* http://openstreetmapdata.com/data/land-polygons
* http://openstreetmapdata.com/data/water-polygons

Shapefiles used in this application are derived from OSM data, © OpenStreetMap contributors.

Matija Obreza's avatar
Matija Obreza committed
35
Create a `data` subdirectory in the directory with the jar file.
36
Extract the shapefile zip archives and move their contents into the newly created `data/` directory. 
Matija Obreza's avatar
Service  
Matija Obreza committed
37
38
as the jar file of this application. You should now have three files in this directory: 

Matija Obreza's avatar
Matija Obreza committed
39
40
41
42
43
	$ find .
	data/land_polygons.shp
	data/land...
	data/water_polygons.shp
	data/water...
Matija Obreza's avatar
Matija Obreza committed
44
	genesys-geo-tools-0.2-SNAPSHOT.jar
Matija Obreza's avatar
Service  
Matija Obreza committed
45

Matija Obreza's avatar
Matija Obreza committed
46
### Running the program
Matija Obreza's avatar
Service  
Matija Obreza committed
47

Matija Obreza's avatar
Matija Obreza committed
48
JAI library creates an AWT window. Run the *Land or Sea* test in headless mode:
Matija Obreza's avatar
Service  
Matija Obreza committed
49

Matija Obreza's avatar
Matija Obreza committed
50
	java -Djava.awt.headless=true -jar genesys-geo-tools-0.2-SNAPSHOT.jar landorsea [options] <inputFile> <outputFile>
Matija Obreza's avatar
Service  
Matija Obreza committed
51

Matija Obreza's avatar
CLI  
Matija Obreza committed
52

Matija Obreza's avatar
Matija Obreza committed
53
54
## Validating Country of Origin ##

Matija Obreza's avatar
Matija Obreza committed
55
56
57
58
59
60
61
62
63
Prepare a CSV file with columns `DECLATITUDE`, `DECLONGITUDE`. The
program will test the geographic coordinates against the country borders and 
report the country ISO3 code in `ORIGCTY_check`.

When the input CSV includes `ORIGCTY`, the program will validate the reported
country against the one identified and report **OK** when they match.

### Country borders

Matija Obreza's avatar
Matija Obreza committed
64
65
66
67
68
69
70
71
72
73
74
75
Download two distinct shapefiles with country borders: 

* http://thematicmapping.org/downloads/world_borders.php (TM_WORLD_BORDERS-0.3)
* http://gadm.org/version2 (six dissolved layers)

Unpack the zip archives and drop the data into the `data/` folder. The application will load
`TM_WORLD_BORDERS-0.3.shp` and `gadm28_adm0.shp` (the top-admin-level shapefile) and 
`gadm28_adm1.shp` (the 2nd-level admin regions shapefile).

The `TM_WORLD_BORDERS` data is used for initial matching. Any mismatch will then be looked up in the
very detailed `GADM0` and `GADM1` layers.

Matija Obreza's avatar
Matija Obreza committed
76
77
### Running the program

Matija Obreza's avatar
Matija Obreza committed
78
	java -Djava.awt.headless=true -jar genesys-geo-tools-0.2-SNAPSHOT.jar country [options] <inputFile> <outputFile>
Matija Obreza's avatar
Matija Obreza committed
79
80


Matija Obreza's avatar
Matija Obreza committed
81
## Features ##
82
83
84

* Accepts CSV as input, produces CSV output

Matija Obreza's avatar
Matija Obreza committed
85
## TODO List ##
Matija Obreza's avatar
CLI  
Matija Obreza committed
86
87
88

* Generate HTML report
* For "Water" entries, report distance to closest land.