# Solar Eclipse Workbench
## Table of contents
[//]: # (- [Solar Eclipse Workbench](#solar-eclipse-workbench))
[//]: # ( - [Table of contents](#table-of-contents))
- [Solar Eclipse Workbench](#solar-eclipse-workbench)
- [Table of contents](#table-of-contents)
- [Installation instructions](#installation-instructions)
- [Installation on macOS](#installation-on-macos)
- [Installation on Ubuntu 22.04](#installation-on-ubuntu-2204)
- [Installation on Windows 11](#installation-on-windows-11)
- [Running Solar Eclipse Workbench](#running-solar-eclipse-workbench)
- [Command line parameters](#command-line-parameters)
- [UI functionality](#ui-functionality)
- [Observing location](#observing-location)
- [Eclipse date](#eclipse-date)
- [Reference moments](#reference-moments)
- [Camera overview](#camera-overview)
- [Simulation mode](#simulation-mode)
- [Job scheduling](#job-scheduling)
- [Interrupting scheduled jobs](#interrupting-scheduled-jobs)
- [Datetime format](#datetime-format)
- [Saving settings](#saving-settings)
- [Script file format](#script-file-format)
- [General remarks](#general-remarks)
- [Commands](#commands)
- [Shortcomings](#shortcomings)
- [Converting scripts from Solar Eclipse Maestro](#converting-scripts-from-solar-eclipse-maestro)
- [Error handling](#error-handling)
- [Development Guide](#development-guide)
- [Installation on macOS](#installation-on-macos-1)
- [Image attributions](#image-attributions)
- [GUI icons](#gui-icons)
## Installation instructions
### Installation on macOS
- Create a new python environment. You can use venv or any python environment manager for this (like anaconda, micromamba, ...)
```bash
python -m venv solareclipseworkbench
```
- For modern Apple Mac computers (using Apple Silicon processors), install [homebrew](https://brew.sh/). Add your homebrew/bin directory to your PATH. Then install gphoto2 using homebrew:
```bash
export PATH=<location_of_homebrew_installation>/bin:$PATH
brew install gphoto2 pkg-config
```
- Install the Solar Eclipse Workbench:
```bash
pip install solareclipseworkbench
```
### Installation on Ubuntu 24.04
- Install poetry by executing the following line in the terminal
```bash
sudo apt install curl git
/usr/bin/curl -sSL https://install.python-poetry.org | sed 's/symlinks=False/symlinks=True/' | /usr/bin/python3 -
```
- Check out the source code:
```bash
git clone https://github.com/AstroWimSara/SolarEclipseWorkbench.git
cd SolarEclipseWorkbench
```
- Install the python environment by executing the following command in the Solar Eclipse Workbench directory
```bash
~/.local/bin/poetry install
~/.local/bin/poetry env activate
# This will show the command to execute the environment. Starts with source ~/.local/share/virtualenvs/SolarEclipseWorkbench-<hash>/bin/activate
```
- Eventually, to make the sound notifications a bit faster, install pygobject:
```bash
sudo apt install libcairo2-dev libgirepository1.0-dev gcc
pip install pygobject
```
### Installation on Windows 11
- GPhoto2 is only available for Linux and macOS. To run Solar Eclipse Workbench, wsl should be used.
- Open a terminal in Windows
- Install wsl by executing the command
```bash
wsl --install
```
- Start using wsl by typing `wsl` in a new terminal.
- Install poetry by executing the following line in the terminal
```bash
curl -sSL https://install.python-poetry.org | sed 's/symlinks=False/symlinks=True/' | python3 -
```
- Check out the source code:
```bash
git clone https://github.com/AstroWimSara/SolarEclipseWorkbench.git
```
- Log out from wsl (by typing `exit`) and log in again.
- Install the python environment by executing the following command in the Solar Eclipse Workbench directory
```bash
cd SolarEclipseWorkbench
~/.local/bin/poetry install
~/.local/bin/poetry env activate
# This will show the command to execute the environment. Starts with source ~/.local/share/virtualenvs/SolarEclipseWorkbench-<hash>/bin/activate
```
- Install needed packages
```bash
sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libxkbcommon-x11-0 libxcb-cursor0 libcairo-dev
```
- Eventually, to make the sound notifications a bit faster, install pygobject:
```bash
sudo apt install libcairo2-dev libgirepository1.0-dev gcc python3-dev gobject-* gir1.2-*
pip install pygobject
```
### Make cameras accessible in wsl
The USB devices are not automatically accessible in wsl. To make the cameras accessible, the following steps should be taken:
- Download the usbipd-win package from [GitHub](https://github.com/dorssel/usbipd-win/releases)
- Install the package
- Start a PowerShell terminal as administrator
- Connect the cameras to the computer
- Execute the following command in the PowerShell terminal
```bash
usbipd list
```
- The cameras should be listed (with their camera name or as MTP USB Device). The camera_id is the busid of the camera. This can be found in the list of usbipd list. The camera_id is a number with a colon and a number (e.g. 1:2). The command to bind the camera to wsl is
```bash
usbipd bind --busid <camera_id>
```
- Attach the camera to wsl by executing the following command in a PowerShell terminal. Make sure that a wsl terminal is also open. **This should be done every time the camera is connected to the computer!!**
```bash
usbipd attach --wsl --busid <camera_id>
```
- The camera should now be available in wsl. You can test this by executing the following command:
```bash
lsusb
```
- The camera can not be accessed yet by the normal user. To make this work, the user should be added to the plugdev group. This can be done by executing the following command in the wsl terminal, and log in into :
```bash
sudo usermod -aG plugdev $USER
```
## Running Solar Eclipse Workbench
- The main script to start is `gui.py`. You can add a parameters to set the needed parameters for the eclipse. Some examples:
```bash
# On macos, start the commands with sudo
sudo ~/.local/bin/poetry run python src/solareclipseworkbench/gui.py -d 2024-04-08 -lon -104.63525 -lat 24.01491 -alt 1877.3
sudo ~/.local/bin/poetry run python src/solareclipseworkbench/gui.py
# In Linux or using WSL on Windows, start the command without sudo
python ~/.local/bin/poetry run src/solareclipseworkbench/gui.py -d 2024-04-08 -lon -104.63525 -lat 24.01491 -alt 1877.3
python ~/.local/bin/poetry run src/solareclipseworkbench/gui.py
```
- There is a problem with `gphoto2`. On macOS, Solar Eclipse Workbench needs to be started with sudo rights to be able to connect to the cameras. In Linux (or Windows using wsl), sudo should not be used.
- The first time you run Solar Eclipse Workbench, some files are downloaded from the internet. Make sure to do this before eclipse day!
### Command line parameters
The following command line parameters can be used to start up gui.py.
| Short parameter | Long parameter | Description |
|-----------------|-----------------------|----------------------------------------------------------------------------|
| -h | --help | Show the help message and exit |
| -d DATE | --date DATE | Date of the solar eclipse (in YYYY-MM-DD format) |
| -lon LONGITUDE | --longitude LONGITUDE | Longitude of the location where to watch the solar eclipse (W is negative) |
| -lat LATITUDE | --latitude LATITUDE | Latitude of the location where to watch the solar eclipse (N is positive) |
| -alt ALTITUDE | --altitude ALTITUDE | Altitude of the location where to watch the solar eclipse (in meters) |
### UI functionality
In the images below, a screenshot of the toolbar and the upper part of the UI are shown.
The icons on the UI toolbar must be clicked from left to right (and the required data must be provided, if applicable) in order for the values in the upper section of the UI to appear. Alternatively, the data can be passed as command line arguments at start-up, as discussed in the previous section.
The functionality of the toolbar buttons is as follows (from left to right):
#### Observing location
- When pressing the "Location" icon, a pop-up window (see screenshot below) will appear, in which you are asked to fill out the longitude, latitude, and altitude of your observing location. Both longitude and latitude are expressed in degrees, the altitude in meters.
- If these data were already inserted before somehow (manually, via command line arguments, or by loading a settings file), these values will appear there (you can modify them as you see fit).
- When pressing the "Plot" button, the specified location (longitude, latitude) will be marked with a red dot on the world map. Note that this plot is not updated automatically when you change the values.
- When pressing the "OK" button, the data are accepted and will be filled out in the top section of the UI.
#### Eclipse date
- When pressing the "Date" icon, a pop-up window (see screenshot below) will appear, in which you can choose the date of the eclipse from a drop-down menu. At any moment in time, the next 20 solar eclipses are included in the list.
- When pressing the "OK" button, the selected eclipse date is accepted and will be filled out in the top section of the UI.
#### Reference moments
- When pressing the "Reference moments" icon, the information for the reference moments of the eclipse is filled out in the top section of the UI.
- The reference moments of the eclipse are:
- C1 (first contact);
- C2 (second contact);
- MAX (maximum eclipse);
- C3 (third contact);
- C4 (fourth contact);
- sunrise;
- sunset.
- The information that is shown for each of these reference moments is:
- Time in the local timezone;
- Time in UTC;
- Countdown;
- Altitude (in degrees);
- Azimuth (in degrees).
- This information can only be populated when the location and the eclipse date have been indicated. Note that the reference moments are not automatically updated in case either of them would be modified.
- Together with the information about the reference moments, the eclipse type (partial / total / annular) will be displayed. For total and annular eclipses, also the time between C2 and C3 will be shown (next to the eclipse type).
#### Camera overview
- When pressing the "Camera" icon, the camera overview in the top section of the UI will be updated. This shows for each camera the following information:
- Camera name;
- Battery level (in percentage);
- Free memory (both in percentage and in GB).
- Apart from updating the camera information in the UI, the following is done for all cameras:
- Syncing the time with the time of the computer the camera is connected to;
- Checking whether for the focus mode and the shooting mode are set to "Manual". If this is not the case, a warning message is logged in the Console where the UI was started.
#### Simulation mode
- The "Simulation" icon will only be available in the toolbar when the UI is started in simulator mode (i.e. with the command line argument `-s` or `--sim`).
- When pressing this icon, a pop-up window (see screenshot below) will appear, in which you can specify when (w.r.t. one of the reference moments of the eclipse) you want to start the simulation.
- When pressing the "OK" button, the selected relative starting time of the simulation will be stored. It will be applied when the jobs are being scheduled (see next section).
#### Job scheduling
- When pressing the "File" icon, a file chooser will pop up, in which you can select the desired TXT file with the scheduled commands.
- When a file with scheduled commands is indeed selected, the scheduled jobs will appear in the bottom section of the UI. As the timing of the commands is expressed in the loaded file w.r.t. the reference moments of the eclipse, you have to make sure that the information about the reference moments has already been filled out in the top section of the UI.
- When jobs are scheduled and hence displayed in the bottom part of the UI, the following information is shown for each job:
- Countdown;
- Execution time in the local timezone;
- Execution time in UTC;
- Representation of the command;
- Description of the command.
- Important to know when in simulation mode:
- Jobs that were scheduled in the past w.r.t. the start of the simulation, will not appear in the list of scheduled jobs.
- The displayed local execution time of the jobs corresponds to the local time at the observing location, so this may be different from the timezone on you laptop (e.g. when you would be practising beforehand at home).
#### Interrupting scheduled jobs
- In case the scheduled jobs would have to be interrupted (e.g. because you realised - hopefully in time - that you did not select the correct file), you have to press the "Stop" icon. The scheduler will be shut down and the scheduled jobs will disappear from the bottom section of the UI.
- Use this icon with caution!
#### Datetime format
- When pressing the "Datetime format" icon, a pop-up window (see screenshot below) will appear, in which you can specify the date and time format.
- When pressing the "OK" button, the selected date and time format will be applied to all dates and times that are or will be displayed in the UI.
- When pressing the "Cancel" button, the old formatting will be kept.
#### Saving settings
- When pressing the "Save" icon, the location and eclipse date (if selected) will be stored in a settings file, together with the applied date and time format.
- The standard settings framework of `PyQt6` (`QSettings`) will be used: it stores the settings as `SolarEclipseWorkbench.ini`.
- Next time you open the UI (from the same location), this settings file will be loaded and the specified data will be made available in the UI.
- In case command line arguments are used to open the UI, these take priority over the values from the settings file.
## Script file format
### General remarks
Test your script before using it during a total solar eclipse! Some cameras can take pictures very fast, some cameras need some time between taking two different pictures.
The following cameras are tested:
- Canon EOS 1000D: 1 picture every two seconds
- Canon EOS 80D: 1 picture every two seconds
- Canon EOS R: 1 picture every two seconds
- Nikon DSC D3400: 1 picture every three seconds
It is possible to take pictures in burst mode. The speed is limited by the speed of the camera (and card).
### Reference moments
The reference moments of the eclipse that used in the scripts are:
- C1: first contact
- C2: second contact
- MAX: maximum eclipse
- C3: third contact
- C4: fourth contact
- SUNRISE: sunrise
- SUNSET: sunset
- LAST: Reference the time to the last command in the script.
### Commands
Solar Eclipse Workbench can use the following commands:
- **take_picture** - Set the aperture (use 8 instead of 8.0), shutter speed and ISO of the camera and take a picture.
```take_picture, C1, -, 0:01:02.0, Canon EOS 80D, 1/1250, 8, 200, "Pre-C1 uneclipsed (Iter. 1)"```
This command will take a picture 1 minutes and 2 seconds before first contact (C1) with the Canon EOS 80D. The ISO will be set to 200, aperture to 8.0 and shutter speed to 1/1250s.
- **take_burst** - Set the aperture, shutter speed and ISO of the camera and take a burst of pictures during 3 seconds (for Canon, Nikon will take 3 pictures in burst mode).
```take_burst, C1, +, 0:00:08.0, Canon EOS 80D, 1/2000, 5.6, 400, 3, "Burst test"```
- **take_bracket** - Set the aperture, shutter speed and ISO of the camera and take a bracket of 5 pictures with the given steps. This method only works in Canon cameras. Make sure to have 5 steps enabled for bracketing. Options for the steps are: +/- 1/3, +/- 2/3, +/- 1, +/- 1 1/3, +/- 1 2/3, +/- 2, +/- 2 1/3, +/- 2 2/3, +/- 3
```take_bracket, C1, +, 0:00:08.0, Canon EOS 80D, 1/2000, 5.6, 400, "+/- 1 2/3", "Bracket test"```
- **voice_prompt** - Play a sound file.
```voice_prompt, C4, -, 00:00:03, C4_IN_3_SECONDS, "3 seconds before C4 voice prompt"```
This command will play the C4_IN_3_SECONDS sound file 3 seconds before fourth contact (C4).
- **sync_cameras** - Read out the camera settings
```sync_cameras, C2, -, 00:00:04, "Sync the camera status"```
- **command** - Execute a command on the computer. This can be used to execute a script or to run a program.
```command, C1, -, 00:00:05, "/home/user/scripts/print_date.sh", "Print the date"```
This command will execute the script `print_date.sh` 5 seconds before first contact (C1). The script should be executable and should not require any user input.
- **for** - Repeat a command a number of times
```for,C1,C4,10,-10,+10```
This command will repeat the commands between C1 and C4 with an interval of 10 seconds. The for loop will start 10 seconds before C1 and will end 10 seconds after C4.
All commands that follow will be repeated up to the **endfor** command. The time for the commands will be adapted automatically.
Example 1:
```
for,C1,C4,10,-10.0,10.0
take_picture,(VAR), +, 0:00:00.0, Canon EOS 80D, 1/1250, 6, 100, "Partial C1-C4"
take_picture,(VAR), +, 0:00:00.0, Canon EOS R, 1/800, 8, 100, "Partial C1-C4"
endfor
```
Example 2:
```
for,C1,C4,600,-20.0,10.0
sync_cameras,(VAR), +, 00:00:00, "Sync the camera status"
endfor
```
- It is also possible to use the following commands from Solar Eclipse Maestro:
| Command | Since version |
|----------------------|---------------|
| FOR,(INTERVALOMETER) | 1.0 |
| TAKEPIC | 1.0 |
| PLAY | 1.0 |
| TAKEBST | 1.0 |
| TAKEBKT | 1.0 |
## Shortcomings
- In normal mode, only one picture every two seconds can be made.
- The computer you are using will probably fall asleep during the solar eclipse. You can prevent this on macOS using [caffeine](https://www.caffeine-app.net/). On Windows, you can use the Windows [powertoys](https://awake.den.dev/).
## Converting scripts from Solar Eclipse Maestro
Scripts from Solar Eclipse Maestro are converted automatically to scripts that can be used by Solar Eclipse Workbench.
## Error handling
If something goes wrong, an error message will be logged in the log file `/tmp/solareclipseworkbench.log`.
## Development Guide
When you want to help with the development of Solar Eclipse Workbench, some extra installation is needed.
### Installation on macOS
- Install poetry by executing the following line in the terminal
```bash
curl -sSL https://install.python-poetry.org | sed 's/symlinks=False/symlinks=True/' | python3 -
```
- Check out the source code:
```bash
git clone https://github.com/AstroWimSara/SolarEclipseWorkbench.git
cd SolarEclipseWorkbench
```
- Install the python environment by executing the following command in the Solar Eclipse Workbench directory
```bash
poetry install
poetry shell
pip3 install PyObjC
```
## Image attributions
### GUI icons
- <a href="https://www.flaticon.com/free-icons/map" title="map icons">Map icons created by Freepik - Flaticon</a>
- <a href="https://www.flaticon.com/free-icons/clock" title="clock icons">Clock icons created by Freepik - Flaticon</a>
- <a href="https://www.flaticon.com/free-icons/camera" title="camera icons">Camera icons created by Freepik - Flaticon</a>
- <a href="https://www.flaticon.com/free-icons/calendar" title="calendar icons">Calendar icons created by Freepik - Flaticon</a>
- <a href="https://www.flaticon.com/free-icons/settings" title="settings icons">Settings icons created by Freepik - Flaticon</a>
- <a href="https://www.flaticon.com/free-icons/stop-sign" title="stop sign icons">Stop sign icons created by Freepik - Flaticon</a>
- <a href="https://www.flaticon.com/free-icons/folder" title="folder icons">Folder icons created by Freepik - Flaticon</a>
- <a href="https://www.flaticon.com/free-icons/simulation" title="simulation icons">Simulation icons created by Freepik - Flaticon</a>
- <a href="https://www.flaticon.com/free-icons/save" title="save icons">Save icons created by Freepik - Flaticon</a>
Raw data
{
"_id": null,
"home_page": "https://github.com/AstroWimSara/SolarEclipseWorkbench",
"name": "solareclipseworkbench",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "astronomy, photography, solar eclipse",
"author": "Sara Regibo",
"author_email": "sararegibo@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a9/67/dbaa920fdbcee882f401c90ddb43ab2edcbc0ab8af2f8edfe2e8961b2312/solareclipseworkbench-1.2.2.tar.gz",
"platform": null,
"description": "# Solar Eclipse Workbench\n\n\n\n## Table of contents\n\n[//]: # (- [Solar Eclipse Workbench](#solar-eclipse-workbench))\n[//]: # ( - [Table of contents](#table-of-contents))\n- [Solar Eclipse Workbench](#solar-eclipse-workbench)\n - [Table of contents](#table-of-contents)\n - [Installation instructions](#installation-instructions)\n - [Installation on macOS](#installation-on-macos)\n - [Installation on Ubuntu 22.04](#installation-on-ubuntu-2204)\n - [Installation on Windows 11](#installation-on-windows-11)\n - [Running Solar Eclipse Workbench](#running-solar-eclipse-workbench)\n - [Command line parameters](#command-line-parameters)\n - [UI functionality](#ui-functionality)\n - [Observing location](#observing-location)\n - [Eclipse date](#eclipse-date)\n - [Reference moments](#reference-moments)\n - [Camera overview](#camera-overview)\n - [Simulation mode](#simulation-mode)\n - [Job scheduling](#job-scheduling)\n - [Interrupting scheduled jobs](#interrupting-scheduled-jobs)\n - [Datetime format](#datetime-format)\n - [Saving settings](#saving-settings)\n - [Script file format](#script-file-format)\n - [General remarks](#general-remarks)\n - [Commands](#commands)\n - [Shortcomings](#shortcomings)\n - [Converting scripts from Solar Eclipse Maestro](#converting-scripts-from-solar-eclipse-maestro)\n - [Error handling](#error-handling)\n - [Development Guide](#development-guide)\n - [Installation on macOS](#installation-on-macos-1)\n - [Image attributions](#image-attributions)\n - [GUI icons](#gui-icons)\n\n## Installation instructions\n\n### Installation on macOS\n\n- Create a new python environment. You can use venv or any python environment manager for this (like anaconda, micromamba, ...)\n\n```bash\npython -m venv solareclipseworkbench\n```\n\n- For modern Apple Mac computers (using Apple Silicon processors), install [homebrew](https://brew.sh/). Add your homebrew/bin directory to your PATH. Then install gphoto2 using homebrew:\n\n```bash\nexport PATH=<location_of_homebrew_installation>/bin:$PATH\nbrew install gphoto2 pkg-config\n```\n\n- Install the Solar Eclipse Workbench:\n\n```bash\npip install solareclipseworkbench\n```\n\n### Installation on Ubuntu 24.04\n\n- Install poetry by executing the following line in the terminal\n\n```bash\nsudo apt install curl git\n/usr/bin/curl -sSL https://install.python-poetry.org | sed 's/symlinks=False/symlinks=True/' | /usr/bin/python3 -\n```\n\n- Check out the source code:\n\n```bash\ngit clone https://github.com/AstroWimSara/SolarEclipseWorkbench.git\ncd SolarEclipseWorkbench\n```\n\n- Install the python environment by executing the following command in the Solar Eclipse Workbench directory\n\n```bash\n~/.local/bin/poetry install\n~/.local/bin/poetry env activate\n# This will show the command to execute the environment. Starts with source ~/.local/share/virtualenvs/SolarEclipseWorkbench-<hash>/bin/activate\n```\n\n- Eventually, to make the sound notifications a bit faster, install pygobject:\n\n```bash\nsudo apt install libcairo2-dev libgirepository1.0-dev gcc\npip install pygobject\n```\n\n### Installation on Windows 11\n\n- GPhoto2 is only available for Linux and macOS. To run Solar Eclipse Workbench, wsl should be used.\n- Open a terminal in Windows\n- Install wsl by executing the command\n\n```bash\nwsl --install\n```\n\n- Start using wsl by typing `wsl` in a new terminal.\n- Install poetry by executing the following line in the terminal\n\n```bash\ncurl -sSL https://install.python-poetry.org | sed 's/symlinks=False/symlinks=True/' | python3 -\n```\n\n- Check out the source code:\n\n```bash\ngit clone https://github.com/AstroWimSara/SolarEclipseWorkbench.git\n```\n\n- Log out from wsl (by typing `exit`) and log in again.\n- Install the python environment by executing the following command in the Solar Eclipse Workbench directory\n\n```bash\ncd SolarEclipseWorkbench\n~/.local/bin/poetry install\n~/.local/bin/poetry env activate\n# This will show the command to execute the environment. Starts with source ~/.local/share/virtualenvs/SolarEclipseWorkbench-<hash>/bin/activate\n```\n\n- Install needed packages\n\n```bash\nsudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libxkbcommon-x11-0 libxcb-cursor0 libcairo-dev\n```\n\n- Eventually, to make the sound notifications a bit faster, install pygobject:\n\n```bash\nsudo apt install libcairo2-dev libgirepository1.0-dev gcc python3-dev gobject-* gir1.2-*\npip install pygobject\n```\n\n### Make cameras accessible in wsl\n\nThe USB devices are not automatically accessible in wsl. To make the cameras accessible, the following steps should be taken:\n- Download the usbipd-win package from [GitHub](https://github.com/dorssel/usbipd-win/releases)\n- Install the package\n- Start a PowerShell terminal as administrator\n- Connect the cameras to the computer\n- Execute the following command in the PowerShell terminal\n\n```bash\nusbipd list\n```\n\n- The cameras should be listed (with their camera name or as MTP USB Device). The camera_id is the busid of the camera. This can be found in the list of usbipd list. The camera_id is a number with a colon and a number (e.g. 1:2). The command to bind the camera to wsl is\n\n```bash\nusbipd bind --busid <camera_id>\n```\n\n- Attach the camera to wsl by executing the following command in a PowerShell terminal. Make sure that a wsl terminal is also open. **This should be done every time the camera is connected to the computer!!**\n\n```bash\nusbipd attach --wsl --busid <camera_id>\n```\n\n- The camera should now be available in wsl. You can test this by executing the following command:\n\n```bash\nlsusb\n```\n\n- The camera can not be accessed yet by the normal user. To make this work, the user should be added to the plugdev group. This can be done by executing the following command in the wsl terminal, and log in into :\n\n```bash \nsudo usermod -aG plugdev $USER\n```\n\n## Running Solar Eclipse Workbench\n\n- The main script to start is `gui.py`. You can add a parameters to set the needed parameters for the eclipse. Some examples:\n\n```bash\n# On macos, start the commands with sudo\nsudo ~/.local/bin/poetry run python src/solareclipseworkbench/gui.py -d 2024-04-08 -lon -104.63525 -lat 24.01491 -alt 1877.3\nsudo ~/.local/bin/poetry run python src/solareclipseworkbench/gui.py\n\n# In Linux or using WSL on Windows, start the command without sudo\npython ~/.local/bin/poetry run src/solareclipseworkbench/gui.py -d 2024-04-08 -lon -104.63525 -lat 24.01491 -alt 1877.3\npython ~/.local/bin/poetry run src/solareclipseworkbench/gui.py\n```\n\n- There is a problem with `gphoto2`. On macOS, Solar Eclipse Workbench needs to be started with sudo rights to be able to connect to the cameras. In Linux (or Windows using wsl), sudo should not be used.\n- The first time you run Solar Eclipse Workbench, some files are downloaded from the internet. Make sure to do this before eclipse day!\n\n### Command line parameters\n\nThe following command line parameters can be used to start up gui.py.\n\n\n| Short parameter | Long parameter | Description |\n|-----------------|-----------------------|----------------------------------------------------------------------------|\n| -h | --help | Show the help message and exit |\n| -d DATE | --date DATE | Date of the solar eclipse (in YYYY-MM-DD format) |\n| -lon LONGITUDE | --longitude LONGITUDE | Longitude of the location where to watch the solar eclipse (W is negative) |\n| -lat LATITUDE | --latitude LATITUDE | Latitude of the location where to watch the solar eclipse (N is positive) |\n| -alt ALTITUDE | --altitude ALTITUDE | Altitude of the location where to watch the solar eclipse (in meters) |\n\n### UI functionality\n\nIn the images below, a screenshot of the toolbar and the upper part of the UI are shown.\n\n\n\nThe icons on the UI toolbar must be clicked from left to right (and the required data must be provided, if applicable) in order for the values in the upper section of the UI to appear. Alternatively, the data can be passed as command line arguments at start-up, as discussed in the previous section.\n\n\n\nThe functionality of the toolbar buttons is as follows (from left to right):\n\n#### Observing location\n\n- When pressing the \"Location\" icon, a pop-up window (see screenshot below) will appear, in which you are asked to fill out the longitude, latitude, and altitude of your observing location. Both longitude and latitude are expressed in degrees, the altitude in meters.\n- If these data were already inserted before somehow (manually, via command line arguments, or by loading a settings file), these values will appear there (you can modify them as you see fit).\n- When pressing the \"Plot\" button, the specified location (longitude, latitude) will be marked with a red dot on the world map. Note that this plot is not updated automatically when you change the values.\n- When pressing the \"OK\" button, the data are accepted and will be filled out in the top section of the UI.\n\n\n\n#### Eclipse date\n\n- When pressing the \"Date\" icon, a pop-up window (see screenshot below) will appear, in which you can choose the date of the eclipse from a drop-down menu. At any moment in time, the next 20 solar eclipses are included in the list.\n- When pressing the \"OK\" button, the selected eclipse date is accepted and will be filled out in the top section of the UI.\n\n\n\n#### Reference moments\n\n- When pressing the \"Reference moments\" icon, the information for the reference moments of the eclipse is filled out in the top section of the UI.\n- The reference moments of the eclipse are:\n - C1 (first contact);\n - C2 (second contact);\n - MAX (maximum eclipse);\n - C3 (third contact);\n - C4 (fourth contact);\n - sunrise;\n - sunset.\n- The information that is shown for each of these reference moments is:\n - Time in the local timezone;\n - Time in UTC;\n - Countdown;\n - Altitude (in degrees);\n - Azimuth (in degrees).\n- This information can only be populated when the location and the eclipse date have been indicated. Note that the reference moments are not automatically updated in case either of them would be modified.\n- Together with the information about the reference moments, the eclipse type (partial / total / annular) will be displayed. For total and annular eclipses, also the time between C2 and C3 will be shown (next to the eclipse type).\n\n#### Camera overview\n\n- When pressing the \"Camera\" icon, the camera overview in the top section of the UI will be updated. This shows for each camera the following information:\n - Camera name;\n - Battery level (in percentage);\n - Free memory (both in percentage and in GB).\n- Apart from updating the camera information in the UI, the following is done for all cameras:\n - Syncing the time with the time of the computer the camera is connected to;\n - Checking whether for the focus mode and the shooting mode are set to \"Manual\". If this is not the case, a warning message is logged in the Console where the UI was started.\n\n#### Simulation mode\n\n- The \"Simulation\" icon will only be available in the toolbar when the UI is started in simulator mode (i.e. with the command line argument `-s` or `--sim`).\n- When pressing this icon, a pop-up window (see screenshot below) will appear, in which you can specify when (w.r.t. one of the reference moments of the eclipse) you want to start the simulation.\n- When pressing the \"OK\" button, the selected relative starting time of the simulation will be stored. It will be applied when the jobs are being scheduled (see next section).\n\n\n\n#### Job scheduling\n\n- When pressing the \"File\" icon, a file chooser will pop up, in which you can select the desired TXT file with the scheduled commands.\n- When a file with scheduled commands is indeed selected, the scheduled jobs will appear in the bottom section of the UI. As the timing of the commands is expressed in the loaded file w.r.t. the reference moments of the eclipse, you have to make sure that the information about the reference moments has already been filled out in the top section of the UI.\n- When jobs are scheduled and hence displayed in the bottom part of the UI, the following information is shown for each job:\n - Countdown;\n - Execution time in the local timezone;\n - Execution time in UTC;\n - Representation of the command;\n - Description of the command.\n- Important to know when in simulation mode:\n - Jobs that were scheduled in the past w.r.t. the start of the simulation, will not appear in the list of scheduled jobs.\n - The displayed local execution time of the jobs corresponds to the local time at the observing location, so this may be different from the timezone on you laptop (e.g. when you would be practising beforehand at home).\n\n#### Interrupting scheduled jobs\n\n- In case the scheduled jobs would have to be interrupted (e.g. because you realised - hopefully in time - that you did not select the correct file), you have to press the \"Stop\" icon. The scheduler will be shut down and the scheduled jobs will disappear from the bottom section of the UI.\n- Use this icon with caution!\n\n#### Datetime format\n\n- When pressing the \"Datetime format\" icon, a pop-up window (see screenshot below) will appear, in which you can specify the date and time format.\n- When pressing the \"OK\" button, the selected date and time format will be applied to all dates and times that are or will be displayed in the UI.\n- When pressing the \"Cancel\" button, the old formatting will be kept.\n\n\n\n#### Saving settings\n\n- When pressing the \"Save\" icon, the location and eclipse date (if selected) will be stored in a settings file, together with the applied date and time format.\n- The standard settings framework of `PyQt6` (`QSettings`) will be used: it stores the settings as `SolarEclipseWorkbench.ini`.\n- Next time you open the UI (from the same location), this settings file will be loaded and the specified data will be made available in the UI.\n- In case command line arguments are used to open the UI, these take priority over the values from the settings file.\n\n## Script file format\n\n### General remarks\n\nTest your script before using it during a total solar eclipse! Some cameras can take pictures very fast, some cameras need some time between taking two different pictures.\n\nThe following cameras are tested:\n\n- Canon EOS 1000D: 1 picture every two seconds\n- Canon EOS 80D: 1 picture every two seconds\n- Canon EOS R: 1 picture every two seconds\n- Nikon DSC D3400: 1 picture every three seconds\n\nIt is possible to take pictures in burst mode. The speed is limited by the speed of the camera (and card).\n\n### Reference moments\n\nThe reference moments of the eclipse that used in the scripts are:\n - C1: first contact\n - C2: second contact\n - MAX: maximum eclipse\n - C3: third contact\n - C4: fourth contact\n - SUNRISE: sunrise\n - SUNSET: sunset\n - LAST: Reference the time to the last command in the script.\n\n### Commands\n\nSolar Eclipse Workbench can use the following commands:\n\n- **take_picture** - Set the aperture (use 8 instead of 8.0), shutter speed and ISO of the camera and take a picture.\n\n```take_picture, C1, -, 0:01:02.0, Canon EOS 80D, 1/1250, 8, 200, \"Pre-C1 uneclipsed (Iter. 1)\"```\n\nThis command will take a picture 1 minutes and 2 seconds before first contact (C1) with the Canon EOS 80D. The ISO will be set to 200, aperture to 8.0 and shutter speed to 1/1250s.\n\n- **take_burst** - Set the aperture, shutter speed and ISO of the camera and take a burst of pictures during 3 seconds (for Canon, Nikon will take 3 pictures in burst mode).\n\n```take_burst, C1, +, 0:00:08.0, Canon EOS 80D, 1/2000, 5.6, 400, 3, \"Burst test\"```\n\n- **take_bracket** - Set the aperture, shutter speed and ISO of the camera and take a bracket of 5 pictures with the given steps. This method only works in Canon cameras. Make sure to have 5 steps enabled for bracketing. Options for the steps are: +/- 1/3, +/- 2/3, +/- 1, +/- 1 1/3, +/- 1 2/3, +/- 2, +/- 2 1/3, +/- 2 2/3, +/- 3\n\n```take_bracket, C1, +, 0:00:08.0, Canon EOS 80D, 1/2000, 5.6, 400, \"+/- 1 2/3\", \"Bracket test\"```\n\n- **voice_prompt** - Play a sound file.\n\n```voice_prompt, C4, -, 00:00:03, C4_IN_3_SECONDS, \"3 seconds before C4 voice prompt\"```\n\nThis command will play the C4_IN_3_SECONDS sound file 3 seconds before fourth contact (C4).\n\n- **sync_cameras** - Read out the camera settings\n\n```sync_cameras, C2, -, 00:00:04, \"Sync the camera status\"```\n\n- **command** - Execute a command on the computer. This can be used to execute a script or to run a program.\n\n```command, C1, -, 00:00:05, \"/home/user/scripts/print_date.sh\", \"Print the date\"```\n\nThis command will execute the script `print_date.sh` 5 seconds before first contact (C1). The script should be executable and should not require any user input.\n\n- **for** - Repeat a command a number of times\n\n```for,C1,C4,10,-10,+10```\n\nThis command will repeat the commands between C1 and C4 with an interval of 10 seconds. The for loop will start 10 seconds before C1 and will end 10 seconds after C4.\nAll commands that follow will be repeated up to the **endfor** command. The time for the commands will be adapted automatically.\n\nExample 1:\n\n```\nfor,C1,C4,10,-10.0,10.0\ntake_picture,(VAR), +, 0:00:00.0, Canon EOS 80D, 1/1250, 6, 100, \"Partial C1-C4\"\ntake_picture,(VAR), +, 0:00:00.0, Canon EOS R, 1/800, 8, 100, \"Partial C1-C4\"\nendfor\n```\n\nExample 2:\n\n```\nfor,C1,C4,600,-20.0,10.0\nsync_cameras,(VAR), +, 00:00:00, \"Sync the camera status\"\nendfor\n```\n\n- It is also possible to use the following commands from Solar Eclipse Maestro:\n\n| Command | Since version |\n|----------------------|---------------|\n| FOR,(INTERVALOMETER) | 1.0 |\n| TAKEPIC | 1.0 |\n| PLAY | 1.0 |\n| TAKEBST | 1.0 |\n| TAKEBKT | 1.0 |\n\n\n## Shortcomings\n\n- In normal mode, only one picture every two seconds can be made.\n- The computer you are using will probably fall asleep during the solar eclipse. You can prevent this on macOS using [caffeine](https://www.caffeine-app.net/). On Windows, you can use the Windows [powertoys](https://awake.den.dev/). \n\n## Converting scripts from Solar Eclipse Maestro\n\nScripts from Solar Eclipse Maestro are converted automatically to scripts that can be used by Solar Eclipse Workbench.\n\n## Error handling\n\nIf something goes wrong, an error message will be logged in the log file `/tmp/solareclipseworkbench.log`.\n\n## Development Guide\n\nWhen you want to help with the development of Solar Eclipse Workbench, some extra installation is needed.\n### Installation on macOS\n\n- Install poetry by executing the following line in the terminal\n\n```bash\ncurl -sSL https://install.python-poetry.org | sed 's/symlinks=False/symlinks=True/' | python3 -\n```\n- Check out the source code:\n\n```bash\ngit clone https://github.com/AstroWimSara/SolarEclipseWorkbench.git\ncd SolarEclipseWorkbench\n```\n\n- Install the python environment by executing the following command in the Solar Eclipse Workbench directory\n\n```bash\npoetry install\npoetry shell\npip3 install PyObjC\n```\n\n\n## Image attributions\n\n### GUI icons\n\n- <a href=\"https://www.flaticon.com/free-icons/map\" title=\"map icons\">Map icons created by Freepik - Flaticon</a>\n- <a href=\"https://www.flaticon.com/free-icons/clock\" title=\"clock icons\">Clock icons created by Freepik - Flaticon</a>\n- <a href=\"https://www.flaticon.com/free-icons/camera\" title=\"camera icons\">Camera icons created by Freepik - Flaticon</a>\n- <a href=\"https://www.flaticon.com/free-icons/calendar\" title=\"calendar icons\">Calendar icons created by Freepik - Flaticon</a>\n- <a href=\"https://www.flaticon.com/free-icons/settings\" title=\"settings icons\">Settings icons created by Freepik - Flaticon</a>\n- <a href=\"https://www.flaticon.com/free-icons/stop-sign\" title=\"stop sign icons\">Stop sign icons created by Freepik - Flaticon</a>\n- <a href=\"https://www.flaticon.com/free-icons/folder\" title=\"folder icons\">Folder icons created by Freepik - Flaticon</a>\n- <a href=\"https://www.flaticon.com/free-icons/simulation\" title=\"simulation icons\">Simulation icons created by Freepik - Flaticon</a>\n- <a href=\"https://www.flaticon.com/free-icons/save\" title=\"save icons\">Save icons created by Freepik - Flaticon</a>\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Tools to photograph solar eclipses",
"version": "1.2.2",
"project_urls": {
"Homepage": "https://github.com/AstroWimSara/SolarEclipseWorkbench",
"Repository": "https://github.com/AstroWimSara/SolarEclipseWorkbench"
},
"split_keywords": [
"astronomy",
" photography",
" solar eclipse"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "88d9747d2a44b4e4f0a7791b5875ce4f16cf530b256911d4865957e6adfe6846",
"md5": "6d32043ad27f5cb6ef039beec6e637ad",
"sha256": "ef3fd0e96cf80097dd6b3b0f17447f9281beb5cb14c8f9583fe9d96fc7616857"
},
"downloads": -1,
"filename": "solareclipseworkbench-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6d32043ad27f5cb6ef039beec6e637ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 22582891,
"upload_time": "2025-08-01T07:48:16",
"upload_time_iso_8601": "2025-08-01T07:48:16.569829Z",
"url": "https://files.pythonhosted.org/packages/88/d9/747d2a44b4e4f0a7791b5875ce4f16cf530b256911d4865957e6adfe6846/solareclipseworkbench-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a967dbaa920fdbcee882f401c90ddb43ab2edcbc0ab8af2f8edfe2e8961b2312",
"md5": "56e2c3e7a711a5b8937e3ec89f9e7d5e",
"sha256": "0553f81f6d3d411404b5ab7fa8cb9dd160db65870a59f329c43959f7bb8f9f80"
},
"downloads": -1,
"filename": "solareclipseworkbench-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "56e2c3e7a711a5b8937e3ec89f9e7d5e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 22505294,
"upload_time": "2025-08-01T07:48:32",
"upload_time_iso_8601": "2025-08-01T07:48:32.152010Z",
"url": "https://files.pythonhosted.org/packages/a9/67/dbaa920fdbcee882f401c90ddb43ab2edcbc0ab8af2f8edfe2e8961b2312/solareclipseworkbench-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 07:48:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AstroWimSara",
"github_project": "SolarEclipseWorkbench",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "solareclipseworkbench"
}
JSON
