151 lines
3.3 KiB
Markdown
151 lines
3.3 KiB
Markdown
<image src="assets/rugreefer.png" width="250" />
|
|
|
|
# Rugreefer
|
|
|
|
Rugreefer is a Dart library for retrieving metadata about geographic coordinates from a [dopecarpet](http://github.com/randogoth/dopecarpet) server. It converts coordinates into a geohash, fetches a gzipped GeoJSON file from the API, and extracts relevant spatial data such as polygons and lines. The library also supports caching with optional expiration to improve performance.
|
|
|
|
## Features
|
|
- Converts latitude/longitude to geohash (precision: 4 characters)
|
|
- Fetches GeoJSON files from a remote API
|
|
- Extracts relevant metadata from polygons and lines
|
|
- Supports caching for performance optimization
|
|
- Optional cache expiration (default: 14 days)
|
|
- Works in Flutter (mobile, desktop, web)
|
|
|
|
## Installation
|
|
Add rugreefer to your `pubspec.yaml`:
|
|
|
|
```yaml
|
|
dependencies:
|
|
rugreefer:
|
|
git:
|
|
url: https://github.com/randogoth/rugreefer.git
|
|
```
|
|
|
|
Then, run:
|
|
```sh
|
|
flutter pub get
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Example
|
|
|
|
To create an instance of `RugReefer`, provide the required parameters:
|
|
|
|
```dart
|
|
import 'package:rugreefer/rugreefer.dart';
|
|
|
|
void main() async {
|
|
final rugReefer = RugReefer(
|
|
apiUrl: 'https://example.com/api', // API endpoint for geospatial data
|
|
categoryMap: 'assets/categories.json', // Path to the JSON asset for category mapping
|
|
enableCacheExpiration: true, // Optional: Enable cache expiration (default: false)
|
|
cacheExpirationDuration: Duration(days: 14), // Optional: Cache expiration duration (default: 14 days)
|
|
cacheSizeThreshold: 20 * 1024 * 1024, // Optional: Cache size threshold in bytes (default: 20MB)
|
|
);
|
|
|
|
final results = await rugReefer.lookup(30.5735040, 34.453125);
|
|
print(results);
|
|
}
|
|
```
|
|
|
|
Example Output:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"in": {
|
|
"bush": ["scrub"],
|
|
"forest": ["forest"]
|
|
}
|
|
},
|
|
{
|
|
"by": {
|
|
"water": ["stream"]
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
## Available Methods
|
|
|
|
### 1. Lookup Metadata
|
|
Perform a geospatial metadata lookup for a given latitude and longitude.
|
|
|
|
```dart
|
|
Future<Map<String, Map<String, List<String>>>> lookup(
|
|
double latitude,
|
|
double longitude, {
|
|
double distanceThreshold = 10.0, // Optional: Distance threshold in meters (default: 10.0)
|
|
});
|
|
```
|
|
|
|
Example:
|
|
```dart
|
|
final metadata = await rugReefer.lookup(37.7749, -122.4194);
|
|
print(metadata);
|
|
```
|
|
|
|
---
|
|
|
|
### 2. Get Current Cache Size
|
|
Get the total size of the cache in bytes.
|
|
|
|
```dart
|
|
Future<int> getCurrentCacheSize();
|
|
```
|
|
|
|
Example:
|
|
```dart
|
|
final cacheSize = await rugReefer.getCurrentCacheSize();
|
|
print("Cache size: ${cacheSize / 1024 / 1024} MB");
|
|
```
|
|
|
|
---
|
|
|
|
### 3. List Cached Files
|
|
List all currently cached files with their sizes and last access times.
|
|
|
|
```dart
|
|
Future<List<Map<String, dynamic>>> listCachedFiles();
|
|
```
|
|
|
|
Example:
|
|
```dart
|
|
final cachedFiles = await rugReefer.listCachedFiles();
|
|
for (var file in cachedFiles) {
|
|
print("File: ${file['file']}, Size: ${file['size']} bytes, Last Access: ${file['lastAccess']}");
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 4. Delete a Specific Cached File
|
|
Delete a specific cached file by its geohash.
|
|
|
|
```dart
|
|
Future<void> deleteCachedFile(String geohash);
|
|
```
|
|
|
|
Example:
|
|
```dart
|
|
await rugReefer.deleteCachedFile('u4pru');
|
|
```
|
|
|
|
---
|
|
|
|
### 5. Clear the Entire Cache
|
|
Delete all cached files and remove their last access times.
|
|
|
|
```dart
|
|
Future<void> clearCache();
|
|
```
|
|
|
|
Example:
|
|
```dart
|
|
await rugReefer.clearCache();
|
|
```
|
|
|
|
## Author
|
|
[@randogoth](https://github.com/randogoth)
|