Module:Sandbox/Matroc/Inapoly/doc


 * Inapoly is a test module to see if a position is located within a polygon (shape). This was presented to me as an issue by a fellow user on hewikivoyage that has list of positions and needed to select those that fit within a polygon area -- Matroc
 * After researching and looking at Python, MatLab, Lua, C++ and Math examples to determine if a point is located within a polygon. I resorted to convertng them (most are very similar) in order to create this Module. As this is experimental and not fully vetted user beware.
 * Not for production use - Should only be used in a Sandbox as a tool or aid...


 * Functions
 * function pointinpoly - main entry point when invoking module inapoly
 * internal local function inapoly - function to compare positions and shape provided
 * internal local function grabmaskinpoly - attempts to retrieve a Mapmask from a page
 * internal local function grabmarkerpoly - attempts to retrieve markers and see listing from a page
 * internal local function getwdcoords - attempts to retrieve latitude/longitude via Wikidata if need be
 * internal local function t1_load - loads table Regions which contains formatted polygons (shapes)
 * internal local function newlat - reworks latitude for map
 * internal local function box - creates a box polygon (shape)
 * Parameters
 * poly --- Minimum of 3 decimal combinations of latitude and longitude in the form 'lat:long" -- each set separated by a comma.
 * 32.932:35.097, 32.909:35.653, 33.293:35.572,32.932:35.097 -- note the first and last are the same... Much larger polygon (shapes) can be entered and used.
 * or enter GeoJSON format such as "[-140.000000,53.435182],[-150.392305,62.866762],[-129.607695,62.866762],[-140.000000,53.435182],". Module will check to see if it begins with a "[" it will be processed and lat/long positions will be reversed.
 * table -- Can be used instead of poly and mapmaskpage (below). Preformatted olygons (shapes) in Module:Sanbox/Matroc/Regions table... table=Negev... the table itself is fixed/set and table in this case means which array member to get.
 * note: -- This may change to allow for loading other tables and a lukfor parameter to be introduced...
 * mapmaskpage -- Can be used instead of poly and table. This will attempt to take a page and extract and use the Mapmask template for the polygon shape. ie.mapmask=Brooklyn/South.
 * Be aware -- The time allocated for running scripts has expired. error message may appear. Let me know if you get any of this type of error and I will examine. (One case I experienced was resolved by replacing 🇦🇩 around a mapmask - these characters may have been entered with a different style keyboard.
 * makebox -- Can be use instead of poly,table and mapmaskpage just for fun... Consists of a latitude and longitude separated by a comma ie. makebox=42.81958,-74.73999 will create a mapmask in the shape of a box in (New York (state) (width and height of approx. 35 kms.
 * Notes: -- Order of precedence -- poly, table, mapmaskpage then makebox - other wise an error may possibly occur...
 * Following can be used for a single check against a polygon (shape) only
 * name --- name of place optional ie. name=Baram Synagogue
 * lat decimal latitude ie. latitude=30.932
 * long --- decimal latitude ie.  longitude=35.932
 * wikidata - wikidata id ie. wikidata=Qnnnn
 * Example:
 * Following can be used to perform multiple checks - multiple checks override any single check (name,lat,long,wikidata combo),,,
 * multi -- Container parameter for multiple checks only - contains 4 subfields for name, latitude, longitude and wikidata -- these can be entered by hand and have to be in the following order: @nname@alatitude@blongitude@wwikidata ID - groupings are separated by a :.
 * @n --- name @nName
 * @a --- latitude- @a32.98
 * @b --- longitude --- @b34.23
 * @w --- wikidata ID - @wQnnnnn
 * Example: multi=@nSomewhere@a33.04290@b35.41458@wQ000110 (can be used for one) -- multi=@nMontfort Castle@a33.0443627@b35.2266088@wQnnnn:@nBaram synagogue@a33.04290@b35.41458@wnnn:@nBeit Shemesh@a31.751389@b34.988611@wQnnnn -- if latitude and longitude will attempt to retrieve using the wikidata ID -- Remember too many can be expensive and cause issues.
 * markerpage - Can be used instead of multi to grab markers and optional listings from an article page and create multiple checks markerpage=Jerusalem. These will be used to create simple markers as output.
 * types -- parameter to use with markerpage - enter types separated by a , ie. types=see,buy,go - an attempt to include these listings for checking against a polygon (shape) will be made.
 * Parameters controlling output
 * mapframe - defaul is no' - to output a mapframe and a mapmask with markers if marker=yes and takes markermatch parameter into consideration - especially if you only want to see matches, non-matches or both on a map.
 * If you already have a mapframe and mapmask on your test page then I would opt out of using mapframe=yes and add show=listing,vicinity,mask to your existing mapframe -- if using oporigtype then you may have to add other types to the show parameter...
 * marker --- yes or no -- to output simple markers - default is yes ...
 * markermatch -- yes or no or both - output (simple markers) matches, non-matches or both if marker=yes and markermatch parameter is set ... - default is both.
 * text - default is no .. textual explanation of matches and non-matches - if marker=yes and text=yes and markermatch=yes, no or both then markers and text will be output accordingly. If marker=no and text=yes then text will be output.
 * sort -- default is no - rudimentary sort (English) of shortened markers being created ..
 * oporigtype default is no - options are yes,no or both - This should retain the original type for display on the mapframe ..
 * Examples:
 * Single check:
 * Multiple check
 * Notes:
 * The use of safesubst: while using the wiki editor you can preview the output and work with parameters to change/reuse it. Once you save/publish - results are finalized and the call to the Module will disappear. safesubst allows the module to do its job prior to processing templates and other processes first. If you do not use safesubst you will see the textual output and if saved or published you will only see textual output. Be sure and copy the module template call to #invoke a module in case you need it again!
 * At times it may be necessary to actually save/publish the Sandbox page and purge the page. You can then reenter wiki editor and experiment some more reusing a copy of the module template call.
 * Simple markers are output as 2 types - listing and vicinity (listing=green=match / vicinity=maroon=non-match)
 * Issues may arise due to the difficulty of text-processing a page to get markers/listings and mapmask. There are multiple variations of how and what templates etc. do and the many oddities that were input by editors not following any standard method of entering them.
 * This is designed as a tool and not really for production. Play safe and use in a Sandbox! -- Have fun! -- Matroc (talk) 04:55, 26 September 2018 (UTC)
 * This is designed as a tool and not really for production. Play safe and use in a Sandbox! -- Have fun! -- Matroc (talk) 04:55, 26 September 2018 (UTC)