Determines which geographical divisions are in a Viewport intersect with the given BBOX.
此脚本不应直接安装。它是供其他脚本使用的外部库，要使用该库请加入元指令 // @require https://update.cn-greasyfork.org/scripts/542477/1688297/wmeGisLBBOX.js
A reference guide for the internal APIs, key methods, and utility functions in the wmeGisLBBOX userscript.
whatsInView(viewportBbox, highPrecision = false, returnGeoJson = false)new wmeGisLBBOX()Instantiates a new wmeGisLBBOX object. Designed to encapsulate the caching layer and provide instance methods for geographic intersection logic.
const bboxApi = new wmeGisLBBOX();
/BBOX JSON/COUNTRIES_BBOX_ESPG4326.json'USA', 'CAN', 'FRA') in this file are used for naming subfolders and as prefixes for country-specific files.Note:
TheSub_levelproperty indicates the maximum administrative subdivision depth available for that country:
Sub_level: 0means only the country (no subdivisions)Sub_level: 1means country + first-level subdivisions (such as states, provinces, territories, regions)Sub_level: 2includes country, first-level, and second-level (such as counties, districts, departments)Sub_level: 3includes a further third-level (such as cities, municipalities), with level 3 subdivisions embedded within the second-level JSON files if present
First-level subdivisions (sub-level-1):
/BBOX JSON/<ISO_ALPHA3>/<ISO_ALPHA3>_BBOX_ESPG4326.json
Within each country folder, this file lists first-level subdivisions, keyed by codes like 'CA', 'TX' for USA. These keys are used for subsequent filenames.
Second-level subdivisions (sub-level-2):
/BBOX JSON/<ISO_ALPHA3>/<ISO_ALPHA3>-<SubL1 Key>_BBOX_ESPG4326.json
A file for each first-level subdivision, named with the country code and the sub-level-1 key (e.g., USA-CA_BBOX_ESPG4326.json for California). This file contains an array of objects, each keyed by a second-level subdivision name (e.g., county, borough, department).
Third-level subdivisions (sub-level-3, if present):
Third-level subdivision data is included as a subdivisions array inside the relevant second-level objects in the sub-level-2 JSON. These deeper subdivisions do not have separate files.
How this convention works:
COUNTRIES_BBOX_ESPG4326.json) yields supported countries and their subdivision depth (via Sub_level), which establishes folder and file naming conventions as well as which levels are available.<ISO_ALPHA3>_BBOX_ESPG4326.json) lists first-level subdivisions (e.g., states for USA, provinces for Canada), using their keys (like "CA", "TX", "ON") for naming second-level JSON files.<ISO_ALPHA3>-<SubL1 Key>_BBOX_ESPG4326.json) details second-level subdivisions. If there are third-level subdivisions, these appear as an array within the corresponding second-level object.Examples:
/BBOX JSON/USA/USA_BBOX_ESPG4326.json/BBOX JSON/USA/USA-AK_BBOX_ESPG4326.jsonsubdivisions arrays inside each borough object in USA-AK_BBOX_ESPG4326.json./BBOX JSON/CAN/CAN_BBOX_ESPG4326.json/BBOX JSON/CAN/CAN-ON_BBOX_ESPG4326.json/BBOX JSON/FRA/FRA_BBOX_ESPG4326.json/BBOX JSON/FRA/FRA-IDF_BBOX_ESPG4326.jsonThis hierarchical and predictable structure enables you to locate bounding box data for any administrative unit by following the keys from each parent subdivision level, and also lets you know which administrative depths are available based on the Sub_level property for each country.
Purpose:
Fetches JSON data from a URL, applying a cache to reduce duplicate remote requests.
Signature:
fetchJsonWithCache(url: string): Promise<Object>
Usage Example:
bboxApi.fetchJsonWithCache('https://<username>.github.io/<repo>/data/countries.json').then((data) => {
console.log(data);
});
Purpose:
Fetches and augments country data with subdivision information, returning a structure where each country is mapped to its first-level subdivisions, which may link further to deeper levels.
Signature:
getCountriesAndSubsJson(): Promise<Object>
How it works:
https://wazedev.github.io/wmeGisLBBOX/BBOX%20JSON/COUNTRIES_BBOX_ESPG4326.jsonhttps://wazedev.github.io/wmeGisLBBOX/BBOX%20JSON/USA/USA_BBOX_ESPG4326.json
(substitute USA with <ISO_ALPHA3> for other countries)https://wazedev.github.io/wmeGisLBBOX/BBOX%20JSON/USA/USA-AK_BBOX_ESPG4326.jsonError Handling:
COUNTRIES_BBOX_ESPG4326.json){
"<ISO_ALPHA3>": {
"name": "<country name>",
"id": "<ISO_ALPHA3>",
"ISO_ALPHA2": "<ISO_ALPHA2>",
"ISO_ALPHA3": "<ISO_ALPHA3>",
"Sub_level": <max subdivision level (integer)>,
"bbox": [
{ "minLon": <number>, "minLat": <number>, "maxLon": <number>, "maxLat": <number> }
]
},
...
}
USA_BBOX_ESPG4326.json)Each key is a state or territory code (e.g. "AK" for Alaska):
{
"AK": {
"name": "Alaska",
"sub_id": "AK",
"sub_num": "02",
"bbox": {
"minLon": -179.231086,
"minLat": 51.175092,
"maxLon": 179.859681,
"maxLat": 71.439786
}
},
"CA": {
"name": "California",
"sub_id": "CA",
"sub_num": "06",
"bbox": {
"minLon": -124.482003,
"minLat": 32.529508,
"maxLon": -114.131211,
"maxLat": 42.009503
}
},
"...": "..."
}
Fields:
name: State or territory namesub_id: State code (same as key)sub_num: Numeric FIPS codebbox: Bounding boxEach state has its own file, e.g.:BBOX JSON/USA/USA-AK_BBOX_ESPG4326.json
Structure:
An array of objects.
Each object has a key for a second-level subdivision (borough/county/district), with its info and further subdivisions.
[
{
"Ketchikan Gateway": {
"sub_num": "130",
"name": "Ketchikan Gateway",
"bbox": {
"minLon": -132.277239,
"minLat": 54.648906,
"maxLon": -129.974167,
"maxLat": 56.406005
},
"subdivisions": [
{
"sub_num": "39010",
"name": "Ketchikan",
"bbox": {
"minLon": -132.277239,
"minLat": 54.648906,
"maxLon": -129.974167,
"maxLat": 56.406005
}
}
]
}
},
{
"Kenai Peninsula": {
"sub_num": "122",
"name": "Kenai Peninsula",
"bbox": {
"minLon": -154.748861,
"minLat": 58.65274,
"maxLon": -148.563026,
"maxLat": 61.426239
},
"subdivisions": [
{
"sub_num": "38460",
"name": "Kenai-Cook Inlet",
"bbox": {
"minLon": -154.748861,
"minLat": 58.65274,
"maxLon": -149.782754,
"maxLat": 61.426239
}
},
{
"sub_num": "68610",
"name": "Seward-Hope",
"bbox": {
"minLon": -151.002241,
"minLat": 59.282299,
"maxLon": -148.563026,
"maxLat": 61.043124
}
}
]
}
}
// ... more districts/counties
]
Fields:
sub_num: Numeric FIPS codename: Subdivision namebbox: Bounding boxsubdivisions: Array of deeper subdivisions (3rd-level, e.g. cities, if present)Other Countries:
Similar conventions. For Canada:
CAN_BBOX_ESPG4326.jsonCAN-ON_BBOX_ESPG4326.json (for Ontario)Practical Example:
// Load all countries and their subdivision meta-data
const countries = await bboxApi.getCountriesAndSubsJson();
// Get United States first-level subdivisions (states/territories)
const usaStates = countries['USA'].subL1; // Example: { AK: {...}, CA: {...}, ... }
const alaska = usaStates['AK'];
// To get Alaska's second-level divisions (boroughs/districts):
const akSubL2Arr = await bboxApi.fetchJsonWithCache('https://wazedev.github.io/wmeGisLBBOX/BBOX%20JSON/USA/USA-AK_BBOX_ESPG4326.json');
// Example: Find bounding box for Ketchikan Gateway in Alaska
// (akSubL2Arr is an array where each object uses the district's name as key)
const ketchikanObj = akSubL2Arr.find((obj) => obj['Ketchikan Gateway']);
const ketchikanGatewayInfo = ketchikanObj['Ketchikan Gateway'];
console.log('Ketchikan Gateway BBOX:', ketchikanGatewayInfo.bbox);
// If a third-level (city/area) exists, it's inside the .subdivisions array:
if (ketchikanGatewayInfo.subdivisions && ketchikanGatewayInfo.subdivisions.length > 0) {
for (const sub3 of ketchikanGatewayInfo.subdivisions) {
console.log(`Third-level: ${sub3.name}`, sub3.bbox);
}
}
Notes:
- To traverse deeper, always follow the keys from the previous level's JSON.
- The presence of a
subdivisionsarray within a second-level object indicates available third-level data (no separate files for sub-level-3).- The availability of subdivision depths for a country can be checked via its
Sub_levelproperty inCOUNTRIES_BBOX_ESPG4326.json.
Purpose:
Identifies which U.S. states, counties (and sub-counties, if present) intersect with a specified viewport bounding box.
Optionally applies high-precision GeoJSON shape intersection to improve accuracy for smaller or irregular regions.
Signature:
getIntersectingStatesAndCounties(viewportBbox: Object, highPrecision?: boolean, returnGeoJson?: boolean): Promise<Object>
Parameters:
viewportBbox (Object):{ minLon: number, minLat: number, maxLon: number, maxLat: number }highPrecision (boolean, default=false):returnGeoJson (boolean, default=false):Process Overview:
USA_BBOX_ESPG4326.json.USA-TX_BBOX_ESPG4326.json).highPrecision is true:returnGeoJson and the geometry truly intersects, attaches its GeoJSON feature.Returned Object Structure:
{
"Texas": {
subL1_id: "TX",
subL1_num: "48",
subL2: {
"Harris": {
subL2_num: "201",
subL3: {
"Houston": {
subL3_num: "39010",
source: "BBOX"
}
// ...other sub-counties if present
},
source: "BBOX", // or "GEOJSON"
geoJsonData: {...} // Only present if returnGeoJson === true & highPrecision === true & intersects
},
// ...other counties
},
source: "BBOX" // or "GEOJSON" if any county used geojson
},
// ...other intersecting states
}
subL3 is omitted or empty.Usage Example:
const viewport = { minLon: -102, minLat: 29, maxLon: -94, maxLat: 36 }; // Texas region
const results = await bboxApi.getIntersectingStatesAndCounties(viewport, true, false);
// results['Texas'].subL2 contains only counties that intersect the viewport
// Each county lists intersecting sub-counties (level-3) under .subL3
With GeoJSON output:
const results = await bboxApi.getIntersectingStatesAndCounties(viewport, true, true);
console.log(results['Texas'].subL2['Harris'].geoJsonData); // GeoJSON feature if intersection confirmed
Notes:
getIntersectingSubdivisions.See Also:
Purpose:
For countries other than USA, identifies which first-level and (if available) second-level subdivisions intersect the specified viewport bounding box.
Signature:
getIntersectingSubdivisions(countryObj: Object, viewportBbox: Object): Promise<Object>
Parameters:
countryObj (Object):ISO_ALPHA3 (string): The 3-letter country code (e.g., "FRA" for France).Sub_level (number): Maximum supported subdivision depth (see File and Folder Convention Summary).viewportBbox (Object):{ minLon: number, minLat: number, maxLon: number, maxLat: number }Process Overview:
Sub_level property to determine available subdivision depth.Sub_level >= 1:
/BBOX JSON/<ISO_ALPHA3>/<ISO_ALPHA3>_BBOX_ESPG4326.jsonSub_level === 2 (country supports second-level subdivisions):
/BBOX JSON/<ISO_ALPHA3>/<ISO_ALPHA3>-<SubL1 Key>_BBOX_ESPG4326.jsonReturned Object Structure:
{
"Île-de-France": {
subL1_num: "11", // Example: region numeric code
subL1_id: "IDF",
source: "BBOX",
subL2: {
"Paris": {
subL2_num: "75",
source: "BBOX"
},
"Yvelines": {
subL2_num: "78",
source: "BBOX"
}
// ...other intersecting second-level subdivisions
}
},
// ...other intersecting first-level subdivisions
}
subL2 may be empty or omitted.Usage Example:
const france = { ISO_ALPHA3: 'FRA', Sub_level: 2 };
const subdivisions = await bboxApi.getIntersectingSubdivisions(france, viewport);
console.log(subdivisions);
// Example result:
// {
// "Île-de-France": {
// subL1_num: "11",
// subL1_id: "IDF",
// source: "BBOX",
// subL2: {
// "Paris": { subL2_num: "75", source: "BBOX" },
// ...
// }
// },
// ...
// }
Notes:
Sub_level is 0 or not present, returns an empty object.See Also:
Purpose:
Prunes empty subdivisions and branches from a nested intersection result.
Signature:
cleanIntersectingData(intersectingCountries: Object): void
Usage Example:
bboxApi.cleanIntersectingData(results);
Purpose:
Fetches a region's GeoJSON shape given its country, subdivision, and sub-subdivision codes, and determines whether that geometry intersects the provided viewport bbox. Optionally, returns the full GeoJSON if an intersection is found.
Signature:
fetchAndCheckGeoJsonIntersection(countyCode: string, subCode: string, subSubCode: string, viewportBbox: Object, returnGeoJson?: boolean): Promise<boolean|Object>
Parameters:
countyCode (string):
"USA").subCode (string):
"TX" for Texas.subSubCode (string):
"201" for Harris County.viewportBbox (Object):
{ minLon: number, minLat: number, maxLon: number, maxLat: number }returnGeoJson (boolean, default=false):
true, returns the full GeoJSON for the intersecting region; otherwise just returns true/false.Process Overview:
GEOJSON/<countyCode>/<subCode>/<countyCode>-<subCode>-<subSubCode>_EPSG4326.geojson[ [minLon, minLat], [minLon, maxLat], [maxLon, maxLat], [maxLon, minLat], [minLon, minLat] ]true (or the full GeoJSON if returnGeoJson is true).true if intersection is found (returnGeoJson === false),returnGeoJson === true),false if no intersection is found."Polygon" and "MultiPolygon"; logs a warning for others.false if any error occurs (network issue, parse error, etc).Usage Example:
const viewport = { minLon: -96.0, minLat: 29.5, maxLon: -94.9, maxLat: 30.2 };
// Returns true if Harris County intersects the viewport
const intersects = await bboxApi.fetchAndCheckGeoJsonIntersection('USA', 'TX', '201', viewport);
// Returns the full GeoJSON FeatureCollection if intersecting and returnGeoJson=true
const geojsonData = await bboxApi.fetchAndCheckGeoJsonIntersection('USA', 'TX', '201', viewport, true);
Example GeoJSON File:
A file such as GEOJSON/USA/TX/USA-TX-201_EPSG4326.geojson contains a standard GeoJSON FeatureCollection:
{
"type": "FeatureCollection",
"name": "US-TX-201_EPSG4326.geojson",
"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:OGC:1.3:CRS84" } },
"features": [
{
"type": "Feature",
"properties": { "STATEFP": "48", "COUNTYFP": "201", "NAME": "Harris" },
"bbox": [-95.960733, 29.497297, -94.908492, 30.170606],
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[-94.978845, 29.676731],
... // (thousands of coordinates omitted)
[-94.978845, 29.676731]
]
]
]
}
}
]
}
Notes:
getIntersectingStatesAndCounties.Polygon/MultiPolygon.hasIntersection()).false and logs an error if fetch or format fails.See Also:
whatsInView(viewportBbox, highPrecision = false, returnGeoJson = false)Purpose:
This is the primary method for determining which countries and their subdivisions are visible within a specific viewport bounding box, with optional high-precision (GeoJSON) intersection logic for USA counties and sub-counties.
Signature:
whatsInView(viewportBbox: Object, highPrecision?: boolean, returnGeoJson?: boolean): Promise<Object>
Parameters:
viewportBbox (Object):{ minLon: number, minLat: number, maxLon: number, maxLat: number }highPrecision (boolean, default = false):returnGeoJson (boolean, default = false):Process Overview:
getIntersectingCountries().Sub_level: 0), returns minimal metadata.getIntersectingStatesAndCounties()getIntersectingSubdivisions()cleanIntersectingData() for a concise tree.Returned Object Structure:
{
"United States": {
ISO_ALPHA2: "US",
ISO_ALPHA3: "USA",
Sub_level: 3,
subL1: {
"Texas": { ... } // See getIntersectingStatesAndCounties structure
}
},
"France": {
ISO_ALPHA2: "FR",
ISO_ALPHA3: "FRA",
Sub_level: 2,
subL1: {
"Île-de-France": {
subL1_num: "11",
subL1_id: "IDF",
// etc...
}
}
}
// ...other intersecting countries
}
Sub_level: 0 (no subdivisions), .subL1 is empty.Usage Example:
const bboxApi = new wmeGisLBBOX();
const viewport = { minLon: -80, minLat: 25, maxLon: -78, maxLat: 28 };
// Find all countries and subdivisions in view using bounding boxes
const results = await bboxApi.whatsInView(viewport);
// Find with high precision (e.g., for US counties/cities) and optional GeoJSON:
const highPrecise = await bboxApi.whatsInView(viewport, true, false);
const geojsonResults = await bboxApi.whatsInView(viewport, true, true);
console.log(results);
console.log(highPrecise);
console.log(geojsonResults);
Notes:
highPrecision, fetching and computing may take longer for the USA due to additional network GeoJSON reads.See Also:
Used by the main prototype; rarely called directly. Documented for completeness.
Checks if two bbox objects intersect (with antimeridian wrap consideration).
Signature:
checkIntersection(bbox1: {minLat, maxLat, minLon, maxLon}, bbox2: {minLat, maxLat, minLon, maxLon}): boolean
Usage Example:
const overlaps = checkIntersection({minLat: ..., maxLat: ..., minLon: ..., maxLon: ...}, {...});
Ray-casting algorithm to determine if a point is inside a polygon.
Signature:
isPointInPolygon(point: [x, y], vs: Array<[x, y]>): boolean
Returns point of intersection between two line segments, or null.
Signature:
segmentIntersection(p1: [x, y], p2: [x, y], q1: [x, y], q2: [x, y]): [x, y] | null
Checks for intersection between two polygons (via edge intersection and point containment).
Signature:
hasIntersection(polygon1: Array<[x, y]>, polygon2: Array<[x, y]>): boolean
const bboxApi = new wmeGisLBBOX();
const viewport = { minLon: -80, minLat: 25, maxLon: -78, maxLat: 28 };
// Basic: Countries and first-level subdivisions
const results = await bboxApi.whatsInView(viewport);
console.log(results);
// With high precision GeoJSON checks
const preciseResults = await bboxApi.whatsInView(viewport, true, false);
console.log(preciseResults);
const texasViewport = { minLon: -102, minLat: 29, maxLon: -94, maxLat: 36 };
const counties = await bboxApi.getIntersectingStatesAndCounties(texasViewport);
console.log(counties);
This project is licensed under the MIT License. See LICENSE for details.
GM_xmlhttpRequest for cross-domain capability (userscript engines).This documentation aims to provide clarity for integrators, maintainers, and contributors on the internal APIs and extension points for wmeGisLBBOX.
The whatsInView function is the core user-facing feature of this userscript, providing interactive map-based insights by identifying all countries and subdivisions currently visible within the Waze Map Editor (WME) viewport.
Key Features:
SDK Integration:
Interfaces with the WME SDK to access the current map extent and other map functionalities, initializing only after all necessary dependencies (WME SDK, WazeWrap, etc.) are fully loaded.
User Interface Setup:
Dynamically creates and registers a custom sidebar tab in the WME, displaying script details, attribution, and interactive options for users.
Popup System:
Presents a popup or sidebar content labeled "What's in View?"—showing detailed geographic information about all regions, countries, and subdivisions currently visible on the map.
Real-time Updates:
Listens for map movement, zoom, or rotation events and automatically refreshes the displayed data whenever the viewport changes, ensuring that region and subdivision information is always current.
Precision and Debug Controls:
UI options allow users to enable/disable high-precision (GeoJSON geometry) processing (for more accurate region detection) and toggle debug logging as needed.
Efficient Resource Handling:
Ensures all required libraries and services are ready before operating, minimizing unnecessary loading or network requests.
Extensibility:
The modular design makes it easy to augment the information shown, integrate with other WME plugins, or add additional region-based features.
Installation:
You can install this script from:
https://WazeDev.github.io/wmeGisLBBOX/whatsInView.js
How It Works:
.whatsInView() API, passing the current viewport.With this plug-in, WME editors gain instant, accurate feedback about the administrative regions present in any area they're viewing—greatly improving context for map edits, reporting, or research.