# 🌍[Oclock](https://azialle.github.io/Oclock/)

An interactive 3D WebGL globe that visualizes real-time daylight cycles. Built with Globe.gl and pre-processed spatial data pipeline.

![GIF of Oclock](demo/demo.gif)

[**View Live Demo**](https://azialle.github.io/Oclock/)

## Data Source

The frontend relies on `countries_data.json`. This file is generated by processing raw GeoJSON to include IANA timezones and center coordinates in terms latitude and longitude.

The raw GeoJSON file, `ne_110m_admin_0_countries.geojson`, was sourced from the official [Globe.gl repository](https://github.com/vasturiano/globe.gl/tree/master/example/datasets).

### Processing Pipeline

The data generation is handled by `timezone_data_generator.py`. This script performs the following:

1. **Geometry Analysis**: Uses `shapely` to find a representative point inside each country's boundary.
2. **Timezone Mapping**: Uses `timezonefinder` to look up the specific IANA timezone string for those coordinates.
3. **Data Injection**: Injects the timezone and coordinates back into the GeoJSON properties for use by the frontend.

## UI & Interaction

- **Hover:** Highlights country boundaries and displays local time.
- **Toggle:** A global switch to display all country time labels simultaneously.
- **Click/Select:** Focuses the camera on the country and keeps the time label active.
- **Search:** Type a specific country on the search field to allow instant navigation to specific country.

## Credits & Dependencies

The project utilized several powerful open-source libraries and data source.

- **[Globe.gl](https://globe.gl/)** – The core visualization framework used for rendering the 3D globe, handling polygon layers, and managing HTML elements. Developed by Vasco Asturiano.
- **[Three.js](https://threejs.org/)** – The underlying WebGL engine used for custom `ShaderMaterial` implementation and 3D scene management.
- **[Solar Calculator](https://github.com/mde/solar-calculator)** – Used for calculating astronomical positions, including the equation of time and solar declination to locate the subsolar point.
- **[TimezoneFinder](https://github.com/pypa/timezonefinder)** – Python library used in the preprocessing pipeline to accurately map coordinates to IANA timezone names.
- **[Shapely](https://github.com/shapely/shapely)** – Used in the preprocessing pipeline to handle complex geometric operations, specifically for calculating `representative_point` logic to ensure timezone accuracy.

## License

This project is licensed under the **MIT License**. You are free to use, modify, and distribute this software. See the `LICENSE` file in the repository for full details.