Golden Hour / Sun Position Calculator implementation

Binding contract

This record describes what an executable surface must bind and validate. It does not claim that a public calculator, package, or production route is deployed.

Record owner

Guth Instruments

Lifecycle

verified-with-binding-errata

Evidence ID

t6-053

Effect

Computation or source lookup only

Input and validation requirements

• Division by zero or invalid inverse-trigonometric arguments can occur if an implementation does not clamp floating-point values to [-1,1] or mishandles polar-day/polar-night cases.
• A fixed -0.833° sunrise altitude mixes geometric altitude with an atmospheric-refraction and solar-radius convention; the same convention must be used consistently for event times.
• Near the poles, event ordering and date assignment can be discontinuous; null or all-day statuses need an explicit schema.
• Longitude degrees, UTC offsets, and hours must not be mixed without the factor 15 degrees per hour or 4 minutes per degree.
• Automatic CoreLocation fill is unavailable in pure offline mode unless the operating system supplies the location; the calculator should clearly distinguish unavailable location from a computed result.
• No local terrain or obstruction model is included, consistent with the honest label, but the UI should not present calculated sunrise or golden-hour times as observed local visibility.

Required corrections

[
  {
    "vector": 4,
    "field": "sunrise/sunset UTC and local for 90E, UTC+5:30",
    "wrong": "12:26:40 UTC / 05:56:40 local",
    "correct": "23:56:40 UTC (prev day) / 05:26:40 local civil (solar 05:56:40 - 6h = UTC; +5.5h = local)",
    "cause": "time-zone sign error: for 90E longitude UTC = solar - 6h; she ADDED the offset, and her \"local civil\" value is actually the solar time"
  }
]

Inspectable interface fixture

The sample below is evidence for interface and validation tests, not a production implementation.

{
  "inputs": {
    "latitude_deg": 0,
    "longitude_deg": 0,
    "date": "2025-03-20",
    "timezone": "UTC",
    "declination_deg": 0,
    "equation_of_time_min": 0,
    "blue_hour_thresholds_deg": [
      -6,
      -4
    ],
    "golden_hour_thresholds_deg": [
      -4,
      6
    ],
    "algorithm_assumptions": "reduced model stated in unit_assumptions"
  },
  "expected_outputs": {
    "sunrise": "05:56:40 UTC",
    "sunset": "18:03:20 UTC",
    "golden_hour_morning": "05:44:00–06:24:00 UTC",
    "golden_hour_evening": "17:36:00–18:16:00 UTC",
    "blue_hour_morning": "05:36:00–05:44:00 UTC",
    "blue_hour_evening": "18:16:00–18:24:00 UTC",
    "curve_samples": [
      {
        "utc": "09:00",
        "elevation_deg": 45,
        "azimuth_deg": 90
      },
      {
        "utc": "15:00",
        "elevation_deg": 45,
        "azimuth_deg": 270
      }
    ]
  },
  "working": "At the equator with declination 0°, sin(elevation)=cos(hour angle). Sunrise: cos(H)=sin(-0.833°)=-0.01454, so H=acos(-0.01454)=90.833°. Time from noon=90.833/15=6.05553 h, hence sunrise=12-6.05553=5.94447 h=05:56:40 and sunset=18.05553 h=18:03:20. For +6°: H=acos(sin 6°)=acos(0.104528)=84°, giving 12-84/15=6.40000 h and 17.60000 h. For -4°: H=acos(sin -4°)=acos(-0.069756)=94°, giving 5.73333 h and 18.26667 h. For -6°: H=acos(-0.104528)=96°, giving 5.60000 h and 18.40000 h. At 09:00, H=-45°, elevation=asin(cos(-45°))=45°; before solar noon the equatorial azimuth is 90°. At 15:00, H=+45°, elevation=45° and azimuth=270°."
}

Other records

Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

• VERIFIED_LEDGER.json
• evidence-tranche6/tranche6-results.json
• tranche errata record