From b85d732d55590693fe1a1b37cc3fbdf2f1a49942 Mon Sep 17 00:00:00 2001
From: Brent Schroeter <brent@secondsystemtech.com>
Date: Sun, 18 May 2025 21:54:55 -0700
Subject: [PATCH] add readme

---
 README.md       | 62 +++++++++++++++++++++++++++++++++++++++++++++++++
 data/README.txt |  1 +
 2 files changed, 63 insertions(+)
 create mode 100644 README.md
 create mode 100644 data/README.txt

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..afb8b57
--- /dev/null
+++ b/README.md
@@ -0,0 +1,62 @@
+# Geo3DP
+
+Open model generator for 3D printable geography based on OpenStreetMap.
+
+## Downloading GIS Data
+
+Geo3DP requires 2 types of data files as input:
+- OpenStreetMap data as a .osm.pbf file. Available via
+  [OSM by the Slice](https://slice.openstreetmap.us/).
+- Elevation data as a GeoTiff file. Available from the SRTM GL1 dataset via
+  [OpenTopography](https://portal.opentopography.org/raster?opentopoID=OTSRTM.082015.4326.1).
+
+## Usage
+
+The included Dockerfile takes care of installing dependencies. To run with
+Docker, (using the ./data folder for input and output files):
+
+
+```sh
+docker build -t geo3dp:latest ./
+docker run --rm -it -v "$(pwd)/data:/app/data" geo3dp:latest \
+    --osm "/app/data/<name of .osm.pbf file>" \
+    --topo "/app/data/<name of .tif file>" \
+    --bbox="<min. longitude>,<min. latitude>,<max. longitude>,<max. latitude>" \
+    --edge-len "<length of long edge of model, typically in mm>" \
+    --output "/app/data/output.stl"
+```
+
+- Latitudes and longitudes are encoded as decimals. That is, values south of the
+  equator or west of the prime meridian are expressed as negative numbers.
+- Note the "=" and quotes on the `--bbox` argument so that negative numbers are
+  not parsed as separate CLI arguments.
+
+Other available options include:
+- `--square`: crops the model area to a square centered within the bounding box
+- `--baseplate-h`: adjusts the height of the rectangular base
+
+## Parallel Rendering
+
+To improve performance, Geo3DP automatically splits the model area into multiple
+tiles to parallelize rendering across available CPU cores. In general, the more
+CPU cores available to the Docker engine, the faster a model will render. The
+number of tiles per side can be adjusted manually with the `--slices` option.
+Refer to `--help` for more details.
+
+## Known Issues
+
+### Combining Rendered Meshes
+
+Due to limitations of the OpenSCAD STL exporter/importer, Geo3DP does not
+perform a proper union calculation of the resulting tiled geometry, but rather
+combines the tiled meshes by aligning them side-by-side. This results in a final
+STL file with a nonsensical internal geometry, but 3D printing slicers don't
+seem to mind. This issue may be at least partially addressed by running with
+`--slices=1` to turn off tiling.
+
+### Topography Smoothing
+
+Geo3DP applies simplistic smoothing to the computed elevation map to mitigate
+artifacts in the GeoTiff data. The smoothing algorithm works well in most cases,
+but could be improved to better handle smoothing at the edges of the model and
+consistency across varying map resolutions.
diff --git a/data/README.txt b/data/README.txt
new file mode 100644
index 0000000..72e9217
--- /dev/null
+++ b/data/README.txt
@@ -0,0 +1 @@
+Input and output data files may be placed in this directory.