mirror of
https://github.com/acamarata/nrel-spa-dart.git
synced 2026-07-01 11:24:25 +00:00
86db6c6bae
* feat: gap-fill API surface parity with nrel-spa JS (v1.0.1) Add formatTime, calcSpa, SpaFormattedResult, SpaFormattedAnglesResult, functionCode parameter for getSpa (spaZa/spaZaInc/spaZaRts/spaAll), incidence field on SpaResult, and export all function code constants. All 48 tests pass including numerical cross-validation against the NREL SPA reference date (Golden CO, 2003-10-17) and surface incidence angle. * docs: add CHANGELOG.md for v1.0.1 release * chore: polish pubspec, fix unused import, add wiki docs
69 lines
1.8 KiB
Markdown
69 lines
1.8 KiB
Markdown
# Quickstart
|
|
|
|
## Install
|
|
|
|
Add to `pubspec.yaml`:
|
|
|
|
```yaml
|
|
dependencies:
|
|
nrel_spa: ^1.0.1
|
|
```
|
|
|
|
Run `dart pub get`.
|
|
|
|
## First Call
|
|
|
|
```dart
|
|
import 'package:nrel_spa/nrel_spa.dart';
|
|
|
|
void main() {
|
|
final result = getSpa(
|
|
DateTime.utc(2024, 3, 15, 17, 0, 0),
|
|
40.7128, // latitude (New York)
|
|
-74.0060, // longitude
|
|
-5.0, // UTC offset (EST)
|
|
);
|
|
|
|
print('Solar zenith: ${result.zenith.toStringAsFixed(4)}°');
|
|
print('Solar azimuth: ${result.azimuth.toStringAsFixed(4)}°');
|
|
print('Sunrise: ${result.sunrise.toStringAsFixed(4)} h');
|
|
print('Solar noon: ${result.solarNoon.toStringAsFixed(4)} h');
|
|
print('Sunset: ${result.sunset.toStringAsFixed(4)} h');
|
|
}
|
|
```
|
|
|
|
## Reading Results
|
|
|
|
`getSpa` returns an `SpaResult`:
|
|
|
|
| Field | Type | Description |
|
|
| --- | --- | --- |
|
|
| `zenith` | `double` | Solar zenith angle (degrees) |
|
|
| `azimuth` | `double` | Solar azimuth angle (degrees from north) |
|
|
| `sunrise` | `double` | Sunrise time (decimal hours, UTC) |
|
|
| `solarNoon` | `double` | Solar noon time (decimal hours, UTC) |
|
|
| `sunset` | `double` | Sunset time (decimal hours, UTC) |
|
|
| `angles` | `List<AngleResult>` | Rise/set times for custom zenith angles |
|
|
|
|
## DateTime Input
|
|
|
|
Always pass UTC `DateTime` values. The `timezone` parameter shifts the output times to local time.
|
|
|
|
```dart
|
|
// Convert local DateTime to UTC before passing
|
|
final local = DateTime(2024, 3, 15, 12, 0, 0);
|
|
final utc = local.toUtc();
|
|
final result = getSpa(utc, lat, lng, utcOffset);
|
|
```
|
|
|
|
## Null Results for Sunrise/Sunset
|
|
|
|
At polar latitudes or in summer/winter extremes, sunrise or sunset may not occur. In those cases, `result.sunrise` and `result.sunset` return `double.nan`. Always check before displaying:
|
|
|
|
```dart
|
|
if (!result.sunrise.isNaN) {
|
|
print('Sunrise: ${result.sunrise}');
|
|
} else {
|
|
print('No sunrise today.');
|
|
}
|
|
```
|