Welcome to WorldAirQualityVisualiser

World Air Quality Visualiser is a full-stack web app for exploring location based live air quality data through 3D visualisations driven by React Three Fiber. Air quality data is provided by the API provided at [https://aqicn.org/]

🏠 Visit Homepage

Install

Prerequisites

• Node.js and npm
• .NET 8 SDK

1. Clone the repository

   git clone https://github.com/the-duckchild/Air-Pollution-Visualiser.git
   cd Air-Pollution-Visualiser

2. Install frontend dependencies

   cd ui
   npm install

3. Install backend dependencies

   cd ../api
   dotnet restore

4. Configure environment variables

   • Create .env file in both ui/ and api/ folders.
   • Edit the 'ui' .env file to include VITE_API_BASE_URL: set to your backend API endpoint.
   • Edit the 'api' .env file to include API_EXTERNAL_KEY: set your API key from [https://aqicn.org/data-platform/token/].
   • For detailed setup, see comments in each .env.example

5. Run the backend

   cd api
   dotnet run

6. Run the frontend

   cd ../ui
   npm run dev

Run tests

7. Run the frontend tests

   cd ../ui
   npm run dev

8. Run the backend tests

   cd api.tests
   dotnet test

Usage

• Visit http://localhost:5173 in your browser.
• Interact with the world map to:
  • Select a region and locate the nearest air pollution monitoring station.
  • View current Air Quality Index figures and see animated 3D visualisations.
  • Watch the live ticker for updates as data changes worldwide.
  • Enjoy the realistic Sun position for the current local time.

Troubleshooting

• .env Issues: Ensure your .env files are correctly copied and contain all required variables and API keys.
• Port Conflicts: The frontend defaults to port 5173, backend typically to 5000 or 8000. Close any apps using these ports or adjust in your config.
• CORS Errors: Double-check your backend CORS configuration (api/appsettings.json or environment variables) to allow requests from your frontend's origin.
• API Key/Quota Issues: If you see “API Limit Exceeded” errors, confirm your external key is valid and not over its usage quota.
• .NET Build Errors: Verify you’ve installed the correct version of the .NET SDK.

Configuration

• Frontend (ui/.env):
  • Set the backend API URL (VITE_API_BASE_URL), map options, and UI features.
• Backend (api/.env, api/appsettings.json):
  • Configure database connection, CORS, and external air quality API keys.
• Styling:
  • Edit ui/src/styles/app.css and ui/src/styles/globals.css for custom designs.
• Map & Visuals:
  • Tweak defaults and behaviour in ui/src/Pages/Home/HomePage.tsx and ui/src/components/AqiVisualiser/AqiVisualiser.tsx.

Structure

1. Backend API

• Program:

  • The program bootstraps the API, ensuring all necessary components are initialized and the application is ready to handle HTTP requests.

• Repository:

  • The repository contains the logic to interact with the API at aqicn.org

• Controller:

  • The controller defines the endpoints to access AQI data by UID(s) or Latitude/Longitude.

• Sanitization:

  • The controller calls the sanitization service to clean and validate user input to prevent invalid data or injection attacks.

2. Data Models

   • The DTO is defined in the backend here
   • The DTO is defined in the frontend here which also contains the logic for sending requests to the backend API.

3. Frontend UI

   • Routing takes place from App

   • This displays the Home page, which currently manages a lot of the state for the app.

   • Form Components:

     • FindDataForNearestStationForm displays the context dependent "hide map" and "show map" button and allows the submission of long/lat data by a map click.

     • MapComponent.tsx manages the map visibility, initial coordinates and user interactions on the map, such as panning and zooming.

     • LocationMapMarker displays the map marker and updates both it's position and lat/long form fields on mouse click.

   • AQIVisualiser:

     • AqiVisualiser is the main 3D visualisation using React Three Fiber to show particle systems with the number of particles based on the current values of air pollutants at the nearest recording station to the selected location.

     • Particle Systems defines the individual particle systems and was inspired by this ThreeJs example, the code for which is here. It also handles collision detection for both other particles and the bounds of the containing box.

     • Clouds and Sun use elements from the React Three Drei library to provide a background for the visualisation. The Sun visualisation reacts to the current local timezone, using the browser-geo-tz and date-fns-tz libraries.

     • Grass provides the ground for the visualisation, and is based on the codesandbox here

   • AQI Figures Displays:

     • AQIFiguresDisplay displays the responsive control panel with the current AQI values for the selected location, the location and local time and controls to activate or deactivate the visualisation for each available pollutant.

     • TickerTape displays a moving ticker-tape display at the bottom of the screen with current AQI values for major world cities. It uses motion/react to create the scroll and updates the live data every ten minutes.

Author

👤 Simon Duck

• Github: @simon-duck
• LinkedIn: @simon-duck

Show your support

Give a ⭐️ if this project helped you!

---

This README was generated with ❤️ by readme-md-generator