Filling out documentation a bit. Add function for generating points within polygons for starting point to create fake customer points

Author: rustprooflabs

db/deploy/001.sql

@@ -227,7 +227,7 @@ BEGIN
 
 	DROP TABLE IF EXISTS faker_store_location;
 	CREATE TEMP TABLE faker_store_location AS
-	SELECT a.place_osm_id, a.place_osm_type, a.place_name, a.road_osm_id,
+	SELECT ROW_NUMBER() OVER () AS id, a.place_osm_id, a.place_osm_type, a.place_name, a.road_osm_id,
 			r.osm_type AS road_osm_type, r.name AS road_name, r.ref AS road_ref,
 			public.ST_LineInterpolatePoint(public.ST_LineMerge(r.geom), random()) AS geom
 		FROM selected_roads a
@@ -240,4 +240,59 @@ $$
 ;
 
 
+
+
+-- From: https://trac.osgeo.org/postgis/wiki/UserWikiRandomPoint
+
+CREATE FUNCTION pgosm_flex_faker.n_points_in_polygon(geom geometry, num_points integer)
+  	RETURNS SETOF geometry 
+    LANGUAGE plpgsql VOLATILE
+  	COST 100
+  	ROWS 1000
+AS $$
+DECLARE
+	target_proportion numeric;
+	n_ret integer := 0;
+	loops integer := 0;
+	x_min float8;
+	y_min float8;
+	x_max float8;
+	y_max float8;
+	srid integer;
+	rpoint geometry;
+BEGIN
+	-- Get envelope and SRID of source polygon
+	SELECT ST_XMin(geom), ST_YMin(geom), ST_XMax(geom), ST_YMax(geom), ST_SRID(geom)
+		INTO x_min, y_min, x_max, y_max, srid;
+	-- Get the area proportion of envelope size to determine if a
+	-- result can be returned in a reasonable amount of time
+	SELECT ST_Area(geom)/ST_Area(ST_Envelope(geom)) INTO target_proportion;
+	RAISE DEBUG 'geom: SRID %, NumGeometries %, NPoints %, area proportion within envelope %',
+					srid, ST_NumGeometries(geom), ST_NPoints(geom),
+					round(100.0*target_proportion, 2) || '%';
+	IF target_proportion < 0.0001 THEN
+		RAISE EXCEPTION 'Target area proportion of geometry is too low (%)', 
+						100.0*target_proportion || '%';
+	END IF;
+	RAISE DEBUG 'bounds: % % % %', x_min, y_min, x_max, y_max;
+	
+	WHILE n_ret < num_points LOOP
+		loops := loops + 1;
+		SELECT ST_SetSRID(ST_MakePoint(random()*(x_max - x_min) + x_min,
+									random()*(y_max - y_min) + y_min),
+						srid) INTO rpoint;
+		IF ST_Contains(geom, rpoint) THEN
+		n_ret := n_ret + 1;
+		RETURN NEXT rpoint;
+		END IF;
+	END LOOP;
+	RAISE DEBUG 'determined in % loops (% efficiency)', loops, round(100.0*num_points/loops, 2) || '%';
+END
+$$
+;
+
+
+
+
+
 COMMIT;

docs/src/SUMMARY.md

@@ -2,4 +2,5 @@
 
 - [What is PgOSM Flex Faker?](pgosm-flex-faker.md)
 - [Quick Start](quick-start.md)
+- [Customize](customize.md)
 - [Docker image](docker-image.md)

docs/src/customize.md

@@ -0,0 +1,45 @@
+# Customize
+
+This section builds on the [Quick Start](quick-start.md) section.
+
+
+## External Postgres connections
+
+The quick start uses the built-in Postgres/PostGIS instance. See
+the PgOSM Flex section on [Using external Postgres connections](https://pgosm-flex.com/postgres-external.html) to use your own Postgres instance.
+This approach does load a lot of data to the target database which may not be
+desired.  Consider using `pg_dump` to load only the target data to your
+database of choice.
+
+
+## Each time is new data
+
+Rerun, save second set.
+
+```sql
+CALL pgosm_flex_faker.point_in_place_landuse();
+CREATE TABLE my_fake_stores_v2 AS
+SELECT *
+    FROM faker_store_location
+;
+```
+
+## Custom Places for Shops
+
+The procedure `pgosm_flex_faker.point_in_place_landuse()` allows overriding
+the inclusion of `retail` and `commercial` landuse.
+This is done by creating a custom `landuse_osm_types` table before
+running the stored procedure.
+
+
+
+```sql
+DROP TABLE IF EXISTS landuse_osm_types;
+CREATE TEMP TABLE IF NOT EXISTS landuse_osm_types AS
+SELECT 'college' AS osm_type
+UNION
+SELECT 'recreation_ground' AS osm_type
+UNION
+SELECT 'vineyard' AS osm_type
+;
+```

docs/src/quick-start.md

@@ -1,6 +1,7 @@
 # Quick Start to PgOSM Flex Faker
 
-Words
+This section covers how to get started with the Faker version of PgOSM Flex.
+
 
 ## Load OpenStreetMap Data
 
@@ -51,44 +52,28 @@ random results.
 
 ## Run Faker generation
 
+The stored procedure `pgosm_flex_faker.point_in_place_landuse()` places points
+along roads that are within (or nearby) specific `landuse` areas.  The generated
+data is available after calling the stored procedure in a temporary table
+named `faker_store_location`.
+The generated data is scoped to named places currently, though that will
+likely become adjustable in the future.
+
+
 ```sql
 CALL pgosm_flex_faker.point_in_place_landuse();
 SELECT COUNT(*) FROM faker_store_location;
 ```
 
 
-Save the data somewhere you want, in a non-temp table.
+The following query saves the data in a new, non-temporary table named
+`my_fake_stores`.
 
-```sql
-CREATE TABLE my_fake_stores AS
-SELECT *
-    FROM faker_store_location
-;
-```
 
 
-Rerun, save second set.
-
 ```sql
-CALL pgosm_flex_faker.point_in_place_landuse();
-CREATE TABLE my_fake_stores_v2 AS
+CREATE TABLE my_fake_stores AS
 SELECT *
     FROM faker_store_location
 ;
 ```
-
-## Custom Places for Shops
-
-The procedure `pgosm_flex_faker.point_in_place_landuse()` allows overriding
-the inclusion of `retail` and `commercial` landuse.
-
-```sql
-DROP TABLE IF EXISTS landuse_osm_types;
-CREATE TEMP TABLE IF NOT EXISTS landuse_osm_types AS
-SELECT 'college' AS osm_type
-UNION
-SELECT 'recreation_ground' AS osm_type
-UNION
-SELECT 'vineyard' AS osm_type
-;
-```