Merge pull request #7 from mugulmd/dev/cleanupV0

Clean-up for v0

Author: mugulmd

README.md

@@ -9,57 +9,56 @@ Claude is built around a standard *client-server* architecture, in which the ser
 More specifically, the Claude server creates a window in which it renders a simple rectangle using OpenGL.
 Hence, the content of the window can be customized using a *fragment shader* provided as input.
 
+You can modify the fragment shader while Claude is running:
+whenever you save this file, the changes will apply in the window.
+
 The Claude server - as its name indicates - also creates a server process that listens for any incoming messages.
 These messages are used to modify the fragment shader's *uniforms*.
 Claude clients connect to the server process and send messages to change uniform values.
 
-> Note: for now only uniforms of type *float* are supported. This should change soon.
-
 How does that make it an audio-visual synchronization tool?
 Several audio live-coding environments work in the exact same way: by connecting to a server in charge of "making sounds" and regularly sending it messages using a *clock* system.
 Therefore, by creating Claude clients in these audio live-coding environments, we can use the same clock to update our fragment shader's uniform, giving the impression that the visuals are synchronized with the audio.
 
-Currently Claude is available in only one live-coding environment: **Sardine**.
+Currently Claude is available in only one live-coding environment: [Sardine](https://github.com/Bubobubobubobubo/sardine).
 It can be used as a regular *sender*, thus allowing to take advantage of the *Sardine Pattern Language* for writing uniform values to send.
 
 ## Install
 
 See [INSTALL](INSTALL.md).
 
-## First test with telnet
+## Usage
 
-To test the installation of Claude, start by simply launching a Claude server:
+### First test with telnet
 
+To test the installation of Claude, start by simply launching a Claude server:
 ```
 cd Claude
 python -m claude_server
 ```
+A window should open, displaying an animated wave.
 
 Then, in another terminal, connect to the server using the *telnet* utility:
-
 ```
 telnet 127.0.0.1 65432
 ```
 
 You can now send messages to the server, try the following ones and see what happens in Claude's window:
-
 ```
-freq 5
-amp .1
-amp .4
-freq 1
-...
+f freq 5
+f amp .1
+f water 1 0 0
+i nb_waves 3
 ```
 
-By default the Claude server uses the [wave](resources/wave.frag) shader, which has two uniforms: `freq` (frequency) and `amp` (amplitude).
-These two parameters allow you to tweak the sine wave you are visualizing on screen.
+By default the Claude server uses the [wave](resources/wave.frag) shader, which has a few uniforms for controlling the output.
+These parameters allow you to tweak the wave(s) you are visualizing on screen.
 
-## Using Claude in Sardine
+### Using Claude in Sardine
 
 Once the Claude extension is installed in Sardine, a Claude client will be initialized when you start a new session.
 
 You can then use the `Claude(...)` alias to send messages to the Claude server:
-
 ```python
 @swim
 def wave(p=2, i=0):
@@ -70,3 +69,51 @@ def wave(p=2, i=0):
 
 This alias takes two positional arguments, the uniform name and value, followed by the usual Sardine send parameters (iterator, divisor, rate).
 Note that you can use patterns for the value argument, thus giving great flexibility during live-coding sessions.
+
+In the previous example, the uniforms sent were simply floats, but we can also send vectors (up to 4 dimensions):
+```python
+@swim
+def wave(p=2, i=0):
+    Claude('water', ['.2 1 .5', 0, '1 .2'], i=i)
+    again(wave, p=2, i=i+1)
+```
+
+Moreover, another optional argument lets us specify the *datatype* that we want to use.
+This argument is called `datatype` but it can be replaced by its alias `dt`:
+```python
+@swim
+def wave(p=2, i=0):
+    Claude('nb_waves', '1 2 3 4 3 2', dt='i', i=i)
+    again(wave, p=2, i=i+1)
+```
+
+> Note: for now only the float and integer datatypes are supported ('f' and 'i').
+> The default datatype is float, hence it is not necessary to specify it.
+
+### Shader live-coding
+
+The `claude_server` application has a few configuration options that can be detailed with:
+```
+python -m claude_server -h
+```
+
+The two most important options are `--res` and `--frag`, which allow you to pass in and use your own fragment shader.
+
+Claude is designed for live-coding: you can edit your fragment shader while Claude is running, and every time you save it Claude will update its content.
+
+Feel free to use the [template shader](resources/template.frag) and [utilities](resources/utils/glsl) provided.
+
+## Contributions
+
+Claude is at an early development stage, and we're actively seeking contributors to help enhance the project.
+
+Contributions can take many forms:
+- general feedback
+- bug reports
+- features requests
+- code improvements
+- documentation
+- tool design ideas
+- demos and tutorials.
+
+There is no official communication channel yet, so please use GitHub issues.

claude_client/ClaudeHandler.py

@@ -6,6 +6,12 @@
 
 
 class ClaudeHandler(Sender):
+    """Sardine client for sending messages to the Claude server.
+
+    Attributes:
+      params['ip']: The IP address to connect to the Claude server.
+      params['port']: The port to connect to the Claude server.
+    """
 
     def __init__(self, params: dict):
         super().__init__()
@@ -19,6 +25,7 @@ def __init__(self, params: dict):
             self._socket = None
 
     def _send(self, message: str):
+        # Send message encoded as raw bytes to Claude server
         if self._socket:
             self._socket.send(message.encode())
 
@@ -36,8 +43,11 @@ def send(
         rate: NumericElement = 1,
         **pattern: ParsableElement,
     ):
+        # Names of the 1st to 4th components of the received vector
         dims = ['x', 'y', 'z', 'w']
 
+        # Add each component of the received vector
+        # to the pattern dict for parsing
         if isinstance(value, list):
             if len(value) > 4:
                 return
@@ -46,13 +56,16 @@ def send(
         else:
             pattern[dims[0]] = value
 
+        # Parse each dimension separately
         reduced = self.pattern_reduce(pattern, iterator, divisor, rate)
 
         deadline = self.env.clock.shifted_time
         for item in reduced:
+            # Build message to send to the Claude server
             message = f'{datatype} {name}'
             for dim in dims:
                 if not dim in item:
                     break;
                 message += f' {item[dim]}'
+            # Schedule sending the message
             self.call_timed(deadline, self._send, message)

claude_server/__main__.py

@@ -1,29 +1,22 @@
 from claude_server.app import ClaudeApp
+from claude_server.cli import create_parser
 
 from moderngl_window import run_window_config
 from moderngl_window.resources import register_dir
 
-from argparse import ArgumentParser
 from pathlib import Path
 
 
 # Command line interface
-parser = ArgumentParser(
-    prog='claude'
-)
-
-parser.add_argument('--res', type=str, default=None)
-parser.add_argument('--frag', type=str, default='wave.frag')
-parser.add_argument('--ip', type=str, default='127.0.0.1')
-parser.add_argument('--port', type=int, default=65432)
-parser.add_argument('--title', type=str, default='Claude')
-parser.add_argument('--size', type=int, nargs=2, metavar=('W', 'H'), default=[800, 600])
-
+parser = create_parser()
 args = parser.parse_args()
 
-# Register resources directories
-ClaudeApp.resource_dir = (Path(__file__).parents[1] / 'resources').resolve()
+# Register resources directory
+internal_resources_dir = (Path(__file__).parents[1] / 'resources').resolve()
+register_dir(internal_resources_dir)
+ClaudeApp.resource_dir = internal_resources_dir
 if args.res:
+    register_dir(args.res)
     ClaudeApp.resource_dir = args.res
 
 # Configuration
@@ -33,5 +26,5 @@
 ClaudeApp.title = args.title
 ClaudeApp.window_size = (args.size[0], args.size[1])
 
-# Start application
+# Start application using a pyglet window
 run_window_config(ClaudeApp, args=['-wnd', 'pyglet'])

claude_server/app.py

@@ -10,7 +10,17 @@
 
 
 class ClaudeApp(mglw.WindowConfig):
+    """Class centralizing the Claude server application.
 
+    This class is in charge of:
+      * window management
+      * rendering with OpenGL
+      * updating uniforms and the shading program when needed.
+
+    It also manages the server process and filewatcher which allow interactivity.
+    """
+
+    # OpenGL version
     gl_version = (3, 3)
 
     # Window configuration
@@ -19,7 +29,7 @@ class ClaudeApp(mglw.WindowConfig):
 
     # Shader configuration
     vertex_shader = 'default.vert'
-    fragment_shader = 'wave.frag'
+    fragment_shader = 'template.frag'
 
     # Server configuration
     ip = '127.0.0.1'
@@ -44,7 +54,7 @@ def __init__(self, **kwargs):
         self.vbo = self.ctx.buffer(vertices.astype('f4').tobytes())
         self.vao = self.ctx.vertex_array(self.program, self.vbo, 'in_vert')
 
-        # Queue for sending messages from server process to application process
+        # Queue for sending messages from server process to rendering process
         self.queue = Queue()
 
         # Create and launch server process
@@ -73,20 +83,27 @@ def __init__(self, **kwargs):
         self.observer.start()
 
         # Uniform cache
+        # Used to reset uniforms to their latest value
+        # after fragment shader is reloaded
         self.uniform_cache = {}
 
     def on_frag_changed(self, event):
+        # Notify rendering process that fragment shader must be reloaded
         self.reload_frag = True
 
     def write_uniform(self, np_dtype, name, value, caching = True):
         try:
+            # Retrieve uniform object using its name
             uniform = self.program.get(name, None)
             if uniform:
+                # Send value as raw bytes
                 uniform.write(np.array(value).astype(np_dtype).tobytes())
         except Exception as e:
             print(e)
             return
 
+        # Uniform value was sent successfully
+        # Store this value in the uniform cache
         if caching:
             self.uniform_cache[name] = {
                 'np_dtype': np_dtype,
@@ -105,28 +122,35 @@ def render(self, time, frametime):
                     vertex_shader=ClaudeApp.vertex_shader,
                     fragment_shader=ClaudeApp.fragment_shader
                 )
+                # Loading was successful
+                # Reset OpenGL objects
+                self.program = program
+                self.vao = self.ctx.vertex_array(self.program, self.vbo, 'in_vert')
+                # Send last known uniform values
+                for name, content in self.uniform_cache.items():
+                    self.write_uniform(content['np_dtype'], name, content['value'], False)
             except Exception as e:
                 print(e)
-            self.program = program
-            self.vao = self.ctx.vertex_array(self.program, self.vbo, 'in_vert')
-            for name, content in self.uniform_cache.items():
-                self.write_uniform(content['np_dtype'], name, content['value'], False)
 
         # Read messages fed from server and update uniforms accordingly
         while not self.queue.empty():
             try:
                 item = self.queue.get_nowait()
                 self.write_uniform(item['np_dtype'], item['name'], item['value'])
-            except Exception:
+            except Exception as e:
+                print(e)
                 pass
 
         # Update time
+        # No need to cache the time uniform value
+        # as it must be sent between each frame
         self.write_uniform('f4', 'time', time, False)
 
         # Render frame
         self.vao.render()
 
     def resize(self, width, height):
+        # Update resolution uniform with new dimensions
         self.write_uniform('f4', 'resolution', (width, height))
 
     def close(self):

claude_server/cli.py

@@ -0,0 +1,44 @@
+from argparse import ArgumentParser
+
+
+def create_parser():
+    """Command line interface parser for the Claude server application."""
+    parser = ArgumentParser(
+        prog='claude_server',
+        description='Start the Claude server application with a given fragment shader.'
+    )
+
+    parser.add_argument(
+        '--res', type=str, default=None,
+        help="Filepath to the resource folder containing the fragment shader.\n"
+             "If left to default value, Claude's internal resources folder will be used."
+    )
+    parser.add_argument(
+        '--frag', type=str, default='wave.frag',
+        help="Filename of the fragment shader to use.\n"
+             "Default: %(default)s"
+    )
+
+    parser.add_argument(
+        '--ip', type=str, default='127.0.0.1',
+        help="Server IP address.\n"
+             "Default: %(default)s"
+    )
+    parser.add_argument(
+        '--port', type=int, default=65432,
+        help="Server port.\n"
+             "Default: %(default)s"
+    )
+
+    parser.add_argument(
+        '--title', type=str, default='Claude',
+        help="Window title.\n"
+             "Default: %(default)s"
+    )
+    parser.add_argument(
+        '--size', type=int, nargs=2, metavar=('W', 'H'), default=[800, 600],
+        help="Window initial size.\n"
+             "Default: %(default)s"
+    )
+
+    return parser