illumipy is a Python module for estimating outside Illumination levels for given location, date and time.
Project description
illumipy is a Python module for estimating outside Illumination levels for given location, date and time. Requires an OpenWeatherMap APIkey
Features
- Provides an estimation of outside brightness level based on weather and astronomical data, location, time and empirical model.
- Calculates a variety of solar parameters that can be used for prediction of solar irradiance and solar energy production
- Can be adjustes for date, time, location, cloud coverage and many more.
- Can be used as imported Python module or accessed directly over CLI with a range of useful options
- Uses the free OpenWeatherMap API
INSTALLATION
Installation is easiest using a package manager like PIP. To install pip run:
python -m ensurepip --upgrade
To install illumipy with pip, run:
pip install illumipy
Source files can be found on GitHub, in case you want to tell install manually.
This package can be used via import function in Python or be run directly as a script with CLI options:
Import
import illumipy
# Create Illumination object using light_data() and pass options
illumipy.data.light_data([OPTIONS])
To use the module, simply import illumipy and call the function data.light_data(): This returns a dictionary object with the following information:
- ['illuminance']: Outside Brightness in Lux
- ['time']: Time used as %-H (e.g. 4 or ~~12)
- ['date']: Date used as YYYY-MM-DD
- ['city']: City Used
- ['country']: Country Used
- ['cloud_coverage']: Cloud coverage in %
- ['et_illuminance']: Extraterrestrial Illuminance in Lux
- ['direct_illuminance']: Direct Illuminance in Lux
- ['horizontal_illuminance']: Horizontal Illuminance in Lux
- ['horizontal_sky_illuminance']: Horizontal Sky Illuminance in Lux
- ['sunrise']: Time of Sunrise as hh:mm
- ['sunset']: Time of sunset as hh:mm
- ['sun_altitude']: Sund altitude at [Time] in degrees.
- ['day']: True if there is daylight at [Time].
- ['clear_sky_index'] = Aproximation of Clear Sky Index based on cloud coverage
- ['cs_irradiance'] = Estimated Clear Sky Irradiance in W/m^2 based on solar altitude.
- ['irradiance'] = Estimated current Irradiance in W/m^2 based on solar altitude and cloud coverage.
- coverage.
- ['air_mass'] = calculated air mass for given solar altitude, based on empirical model.
- ['azimuth'] = Calculated solar azimuth for given time and location.
- ['declination'] = calculated solar declination angle for given date.
- ['LSTM'] = Local standard time meridian in degrees.
- ['EOT'] = Equation of Time.
It Takes the following arguments:
- time: str=[0-24]
- date: str=[YYYY-MM-DD]
- city: str=['City']
- country: str=['Country']
- api_key: str=['api_key']
- cloud_coverage: int=[0-100]
if no arguments are provided, defaults to values defined in defaults.py
Command line
To use as script with CLI run <python -m illumipy>. To get a list of available CLI options run <
python -m illumipy -h
> usage: __main__.py [-h] [-t TIME] [-d DATE] [-c CITY]
[-C COUNTRY] [-a API]
[-o OUTPUT [OUTPUT ...]] [-D] [-v] [-A] [-s]
General-purpose solar brightness calculator.
options:
-h, --help show this help message and exit
-t TIME, --time TIME Time of the day in hours (0-24, e.g. 4
or 12). Defaults to current time if not
specified.
-d DATE, --date DATE Date as YYYY-MM-DD (e. g. 2023-06-01).
Defaults to current date if not
specified.
-c CITY, --city CITY City name (e. g. Berlin). Defaults to
{CITY_DEFAULT} if not specified.
-C COUNTRY, --Country COUNTRY
Country name (e. g. Germany). Defaults
to {COUNTRY_DEFAULT} if not specified.
-a API, --api API OpeWeather API-Key (required).
Alternatively, a default API key can be
defined in main.py
-o OUTPUT [OUTPUT ...], --output OUTPUT [OUTPUT ...]
Define the parameters to be returned.
Defaults to 'Illuminance' if not
specified. To see available values try
illumipy [-o|--output] help
-D, --debug Print lots of debugging statements
-v, --verbose Be verbose
-A, --all Print out entire dataset. Default is
just the Illuminance in Lux
-s, --short Print only values, no description
Current issues
-
cloud level, sunrise and sunset are not available for dates in the past. Results might therefore be unreliable. Times for sunrise and sunset will always be for the current day.
-
at 100% cloud coverage, Results might be unreliable.
Requirements
- Python3
- Python packages:
- requests
- logging
- math
- sys
- datetime
- argparse
- OpenWeatherMap API-Key
About
Author: Kalle Fornia
GitHub: https://github.com/duckwilliam/illumipy
PyPi: https://pypi.org/project/illumipy
Version: 1.3.1
10/2023
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for illumipy-1.4.26-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | f97838ecac026ea92c980dbbdb4d376b6fd15d56f71bf1d40fe60543d52c191d |
|
| MD5 | b37b02a9500177cbb2e07f7626141840 |
|
| BLAKE2b-256 | 700f9a32ac7ec2597924d5f6ac04ce8f0f9a40622e1ed674174c92ed9e25d2a8 |
