Adjusted examples README for easier project overview

Author: Gedusim

examples/README.md

@@ -9,36 +9,94 @@ Some scripts have additional dependencies; Check `README.md` in the repository r
 If you set up config.py with your username and API token, you won't have to enter them every time you run a script.
 Be aware that API tokens are only valid for a few days.
 
-##### Beware:
-Python imports search for the modules in the current folder and in installed packages. So, if you haven't installed 
-pyghthouse as a package, you need to change the imports of the files in this folder to work.
 
-In the repository root directory should be a file called `example.py`. This file shows the usage of imports of 
-pyghthouse without having it installed as a package. 
-Note: To use the imports the same way as `example.py`, your skript has to be in the same folder.
 
-### Available functions
-Here you can find a list of functions containing in this package.
+## Ways of programming a pyghthouse script
 
-`from_html(html_color)`
-Converts an HTML color string like FF7F00 or #c0ffee to RGB
 
-`from_hsv(h: float, s: float, v: float)`
-Converts HSV (float values between 0 and 1) colors to RGB.
+The Pyghthouse library has two intended ways of usage:
 
-###### The class `Pyghthouse` with
-`Pyghthouse(username: str, token: str, ...)`
-Set up the `Pyghthouse` object. Needed arguments are `username` and `token`. Optional arguments and further explanation
-can be found in the class definition (see `pyghthouse\ph.py`)
+- Passing a callback function at creation with `Pyghthouse(..., callback=function)` or with the method `Pyghthouse.set_image_callback(callback)`
 
-`Pyghthouse.empty_image()`
-Creates a black image.
-This function can also be called with an instance of the `Pyghthouse` object (*`<instance name>.empty_image()`*)
+- Setting the currently shown canvas with `Pyghthouse.set_image()`
 
-`<instance name>.set_image(image)`
-Sends the given `image`.
 
-`<instance name>.close()`
-Closes the connection. 
+### Programming with callback
 
-*More functions can be found in `pyghthouse\ph.py`*
+The following examples uses callback functions:
+
+- `huecircle.py`
+- `noisefill.py`
+- `rainbow.py`
+- `rgbfill.py`
+- `rgbscan.py`
+- `twopoints.py`
+
+In summary, we first need a callback function to create images when called. After that, we initialize the pyghthouse routine. 
+
+When we now start the pyghthouse routine, images will be generated by the given callback function. Generated images are then send to the server. This will happen in an interval given by the frame_rate.
+
+The pyghthouse routine is now running asynchronous to the main script.
+
+**Important to notice** is, that the pyghthouse routine will end when the main script ends. To let a pyghthouse routine run forever (until error or keyboard interrupt), the `keep_running()` method can be used.
+
+
+### Programming with set_image
+
+The following examples use `set_image`:
+
+- `movingdot.py`
+- `whitefill.py`
+
+Compared to the callback function, `set_image` is a lot simpler.
+
+We again need to initialize and start the pyghthouse routine. After that, we only need to call `set_image(new_image)` to send images to the server.
+
+**Important to notice** is, that `set_image`does not wait until the image is send. This means that we can overwrite the currently set image by setting a new one without waiting for the send. So to ensure important frames to be send, we recommend to use the method `wait()`.
+
+
+
+## Pyghthouse package content
+
+
+### The class `pyghthouse.Pyghthouse` with
+
+- `Pyghthouse(username: str, token: str, ...)`:
+    
+    Set up the `Pyghthouse` object. Needed arguments are `username` and `token`. Optional arguments, like `frame_rate` and further explanations can be found in the class definition (see `pyghthouse\ph.py`)
+
+
+- `Pyghthouse.start()`
+
+    Starts the pyghthouse routine and opens the websocket connection. 
+
+
+- `Pyghthouse.stop()`
+    
+    Stops the pyghthouse routine and closes the websocket connection. 
+
+
+- `Pyghthouse.empty_image()`
+
+    A static method which creates a black image.
+    This function can also be called with an instance of the `Pyghthouse` object (*`<instance name>.empty_image()`*)
+
+
+- `Pyghthouse.set_image(image)`
+    
+    Set the Pyghthouse canvas to `image`. Every `1/frame_rate` seconds, the last image set is send by the pyghthouse routine.
+
+
+*More functions can be found in `pyghthouse\ph.py`*
+
+
+### Utils functions
+Here are additional functions in the pyghthouse package.
+
+- `pyghthouse.utils.from_html(html_color)`:
+
+    Converts an HTML color string like FF7F00 or #c0ffee to RGB
+
+- `pyghthouse.utils.from_hsv(h: float, s: float, v: float)`:
+
+    Converts HSV (float values between 0 and 1) colors to RGB.