Merge remote-tracking branch 'origin/v2'

Lyle-zhang · Jan 7, 2017 · 68efa21 · 68efa21
2 parents e5d6e05 + 42ce221
commit 68efa21
Show file tree

Hide file tree

Showing 8 changed files with 317 additions and 225 deletions.
diff --git a/AUTHORS b/AUTHORS
@@ -1,5 +1,6 @@
 Listed in alphabetic order, categorized by source:
 
+https://github.com/cameronleger
 https://github.com/cj-zeiger
 https://github.com/GenericStudent
 https://github.com/Grelek

diff --git a/README.md b/README.md
@@ -1,12 +1,14 @@
 # himawaripy
 *Put near-realtime picture of Earth as your desktop background*
 
+![24 hours long animation by /u/hardypart](https://i.giphy.com/l3vRnMYNnbhdnz5Ty.gif)
+
 himawaripy is a Python 3 script that fetches near-realtime (10 minutes delayed)
 picture of Earth as its taken by
 [Himawari 8 (ひまわり8号)](https://en.wikipedia.org/wiki/Himawari_8) and sets it
 as your desktop background.
 
-Set a cronjob that runs in every 10 minutes to automatically get the
+Set a cronjob (or systemd service) that runs in every 10 minutes to automatically get the
 near-realtime picture of Earth.
 
 ## Supported Desktop Environments
@@ -24,74 +26,100 @@ near-realtime picture of Earth.
 * any other desktop environments that are not mentioned above.
 
 ## Configuration
-You can configure the level of detail, by modifying the script. You can set the
-global variable `level` to `4`, `8`, `16`, or `20` to increase the quality (and
-thus the file size as well). Please keep in mind that it will also take more
-time to download the tiles.
 
-You can also change the path of the latest picture, which is by default
-`~/.himawari/himawari-latest.png`, by changing the `output_file` variable.
+```
+usage:  [-h] [--version] [--auto-offset | -o OFFSET] [-l {4,8,16,20}]
+        [-d DEADLINE] [--save-battery] [--output-dir OUTPUT_DIR]
+
+set (near-realtime) picture of Earth as your desktop background
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+  --auto-offset         determine offset automatically
+  -o OFFSET, --offset OFFSET
+                        UTC time offset in hours, must be less than or equal
+                        to +10
+  -l {4,8,16,20}, --level {4,8,16,20}
+                        increases the quality (and the size) of each tile.
+                        possible values are 4, 8, 16, 20
+  -d DEADLINE, --deadline DEADLINE
+                        deadline in minutes to download all the tiles, set 0
+                        to cancel
+  --save-battery        stop updating on battery
+  --output-dir OUTPUT_DIR
+                        directory to save the temporary background image
+```
+
+Most of the time himawaripy can accurately detect your timezone if you pass the flag `--auto-offset`, although you may
+also set it manually by `-o` (or `--offset`) flag. If your timezone is beyond GMT by more than 10 hours, use the closest
+one (either `+10` or `-12`).
+
+Increasing the level will increase the quality of the image as well as the time taken to download all the tiles and the
+memory consumption. For instance choosing 20 will make himawaripy use ~700 MiB of memory at its peak and the image will
+be around ~200 MB.
+
+You should set a deadline compatible with your cronjob (or timer) settings to assure that script will terminate in X
+minutes before it is started again.
+
+You might use `--save-battery` to disable refreshing while running on battery power.
 
 ### Nitrogen
 If you use nitrogen for setting your wallpaper, you have to enter this in your
 `~/.config/nitrogen/bg-saved.cfg`.
 
-    [:0.0]
-    file=/home/USERNAME/.himawari/himawari-latest.png
-    mode=4
-    bgcolor=#000000
-
-## Prerequisites
+```
+[:0.0]
+file=/home/USERNAME/.himawari/himawari-latest.png
+mode=4
+bgcolor=#000000
+```
 
-You need a valid python3 installation including the python3-setuptools package:
-
-    sudo apt install python3
-    sudo apt install python3-setuptools 
-
 ## Installation
+* You need a valid python3 installation including the python3-setuptools package
 
-    cd ~
-    git clone https://github.com/boramalper/himawaripy.git
-
-    # configure
-    cd ~/himawaripy/
-    vi himawaripy/config.py
+```
+cd ~
+git clone https://github.com/boramalper/himawaripy.git
 
-    # install
-    sudo python3 setup.py install
+# install
+sudo python3 setup.py install
 
-    # test whether it's working
-    himawaripy
+# test whether it's working
+himawaripy --auto-offset
 
-    # Get the installation path of himawaripy by running the command
-    which -- himawaripy
+# Get the installation path of himawaripy by running the command
+which -- himawaripy
 
-    # Set himawaripy to be called periodically
+# Set himawaripy to be called periodically
 
-        ## Either set up a cronjob
-            crontab -e
+    ## Either set up a cronjob
+        crontab -e
 
-            ### Add the line:
-            */10 * * * * <INSTALLATION_PATH>
+        ### Add the line:
+        */10 * * * * <INSTALLATION_PATH> # command line arguments here
 
-        ## OR, alternatively use the provided systemd timer
+    ## OR, alternatively use the provided systemd timer
 
-            ### Configure
-            vi systemd/himawaripy.service
-            # Replace "<INSTALLATION_PATH>" with the output of the aforementioned command.
+        ### Configure
+        vi systemd/himawaripy.service
+        # Replace "<INSTALLATION_PATH>" with the output of the aforementioned command and command line arguments
 
-            ### Copy systemd configuration
-            cp systemd/himawaripy.{service,timer} $HOME/.config/systemd/user/
+        ### Copy systemd configuration
+        cp systemd/himawaripy.{service,timer} ~/.config/systemd/user/
 
-            ### Enable and start the timer
-            systemctl --user enable --now himawaripy.timer
+        ### Enable and start the timer
+        systemctl --user enable --now himawaripy.timer
+```
 
 ### For KDE Users
 #### KDE 5.7+
-To change the wallpaper in KDE 5.7+, desktop widgets must be unlocked. If you dom't want to leave them unlocked, the pre-KDE 5.7 method can still be used.
+To change the wallpaper in KDE 5.7+, desktop widgets must be unlocked. If you dom't want to leave them unlocked,
+the pre-KDE 5.7 method can still be used.
 
 To unlock desktop widgets ([from the KDE userbase](https://userbase.kde.org/Plasma#Widgets)):
-> Open the Desktop Toolbox or the Panel Toolbox or right click on the Desktop - if you see an item labeled Unlock Widgets then select that, and then proceed to add widgets to your Desktop or your Panel. 
+> Open the Desktop Toolbox or the Panel Toolbox or right click on the Desktop - if you see an item labeled Unlock
+> Widgets then select that, and then proceed to add widgets to your Desktop or your Panel. 
 
 #### Before KDE 5.7
 > So the issue here is that KDE does not support changing the desktop wallpaper
@@ -112,44 +140,48 @@ Many thanks to [xenithorb](https://github.com/xenithorb) [for the solution](http
 
 ### For Mac OSX Users
 
-OSX has deprecated crontab, and replaced it with `launchd`. To set up a launch agent, copy the provided sample `plist` file in `osx/com.user.himawaripy.plist` to `~/Library/LaunchAgents`, and edit the following entries if required
+OSX has deprecated crontab, and replaced it with `launchd`. To set up a launch agent, copy the provided sample `plist`
+file in `osx/org.boramalper.himawaripy.plist` to `~/Library/LaunchAgents`, and edit the following entries if required
 
     mkdir -p ~/Library/LaunchAgents/
-    cp osx/com.user.himawaripy.plist ~/Library/LaunchAgents/
+    cp osx/org.boramalper.himawaripy.plist ~/Library/LaunchAgents/
 
-* `ProgrammingArguments` needs to be the `/path/to/himawaripy/installation`. This *should* be `/usr/local/bin/himawaripy` by default, but himawaripy may be installed elsewhere.
+* `ProgrammingArguments` needs to be the path to himawaripy installation. This *should* be `/usr/local/bin/himawaripy`
+by default, but himawaripy may be installed elsewhere.
 
-* `StartInterval` controls the interval between successive runs, set to 10 minutes (600 seconds) by default, edit as desired.
+* `StartInterval` controls the interval between successive runs, set to 10 minutes (600 seconds) by default,
+edit as desired.
 
 Finally, to launch it, enter this into the console:
 
-    launchctl load ~/Library/LaunchAgents/com.user.himawaripy.plist
+    launchctl load ~/Library/LaunchAgents/org.boramalper.himawaripy.plist
 
 
 ## Uninstallation
-    # Remove the cronjob
-    crontab -e
-    # Remove the line
-    */10 * * * * <INSTALLATION_PATH>
 
-    # OR if you used the systemd timer
-    systemctl --user disable --now himawaripy.timer
-    rm $HOME/.config/systemd/user/himawaripy.{timer,service}
+```
+# Remove the cronjob
+crontab -e
+# Remove the line
+*/10 * * * * <INSTALLATION_PATH>
 
-    # Remove the data directory
-    # By default, `~/.himawari`. Check `output_file` variable in config.py
-    # in case you've changed it.
-    rm -rf ~/.himawari
+# OR if you used the systemd timer
+systemctl --user disable --now himawaripy.timer
+rm $HOME/.config/systemd/user/himawaripy.{timer,service}
 
-    # Uninstall the package
-    sudo pip3 uninstall himawaripy
+# Uninstall the binary
+sudo rm -f <INSTALLATION_PATH>
+
+# Uninstall the package
+sudo pip3 uninstall himawaripy
+```
+
+
+`<INSTALLATION_PATH>` can be found using the command `which -- himawaripy`.
 
 If you would like to share why, you can contact me on github or
 [send an e-mail](mailto:bora@boramalper.org).
 
-## Example
-![Earth, as 2016/02/04/13:30:00 GMT](http://i.imgur.com/4XA6WaM.jpg)
-
 ## Attributions
 Thanks to *[MichaelPote](https://github.com/MichaelPote)* for the [initial
 implementation](https://gist.github.com/MichaelPote/92fa6e65eacf26219022) using