Update readme, add Lua.md and update Scene.md

Author: j-miet

README.md

@@ -1,11 +1,21 @@
-![](docs/Images/Demo/default.png)
+# Simple ray tracer for pixel-themed scenes and animations
 
-> More demo images can be found [here](docs/Images/Demo/)
+| ![](docs/Images/Demo/default.png) |
+|:--:|
+|Static base scene|
+
+
+| ![](docs/Images/defaultGif.gif) |
+|:--:|
+| Animation from base scene|
+
+> More static demo images can be found [here](docs/Images/Demo/)
 
 ## Table of contents
 
 - [<u>How to use</u>](#how-to-use)
 - [<u>Scene</u>](#scene)
+    - [<u>Scripting</u>](#scripting)
 - [<u>Pixel-look</u>](#pixel-look)
 - [<u>Building from source</u>](#building-from-source)
 - [<u>Running tests</u>](#running-tests)
@@ -14,6 +24,9 @@
 
 ## How to use
 
+**Executables for Windows** (and probably Linux-x64) will be added soon. Otherwise you need to
+[build from source](#building-from-source).
+
 To produce an output image, paths for scene and output files are required:
 
 ```bash
@@ -27,6 +40,7 @@ call default image opener program via shell execution:
 PixelRay -i scene.json -o output.png -p
 ```
 
+To avoid file path issues, just keep scene (and script) file in the same directory with executable
 
 #### All commands
 
@@ -36,11 +50,30 @@ PixelRay -i scene.json -o output.png -p
 
 - `-o <path>` or `--output <path>` 
 
-    Output file path. Image format is either **png** or **ppm**-
+    Output file path. Image format is either **.png** or **.ppm**.
 - `-p` or `--preview`:
 
     Attempts to open the output image after rendering by executing the image file, thus calling the default viewing 
     tool in process. Only available for png images as basic editors seldom support ppm.
+
+- `-s <luaScript> <frameCount> {gif}` or `--script <luaScript> <frameCount> {gif}`
+
+    Uses the static scene from `-i` command as a baseline then runs Lua script to produce output frames into 
+    `./frames` directory. Output format is always **png**, frame count defaults to 60 if frameCount is not a valid integer value.
+    - script file uses Lua language and must there end in .lua
+    - cannot be used with output or preview flags
+    - automatically flushes `frames` directory to remove old images
+    - can optionally pass `-g` / `--gif` flag to produce a GIF file from saved frames.
+
+    Example:
+    
+    ```bash
+    PixelRay -i scene.json -s script.lua 30 -g
+    ```
+    
+    produces files frame0.png to frame29.png in `./frames` and 
+    then combines these into a gif file as `outputGif.gif`
+
 - `--debug <mode>`
 
     Renders image based on selected debug mode. These are:
@@ -54,11 +87,25 @@ PixelRay -i scene.json -o output.png -p
 
 ## Scene
 
+> Scene file and animation script templates can be found in [here](scene-template).
+
 Scenes use **json** format.
-Default scene file can be found [here](docs/scene.json).
 
 For all scene parameters and their explanations, see [Scene.md](docs/Scene.md)
 
+### Scripting
+
+Scripts use [Lua programming language](https://www.lua.org/start.html) embedded into C# 
+via [MoonSharp](https://github.com/moonsharp-devs/moonsharp).
+
+Scripting can be applied to
+
+- object transforms (translation/positioning, scaling, rotations)
+- camera (position, forward/upward direction, fov, aspect ratio)
+
+For scripting API, see [Lua.md](docs/Lua.md)
+
+
 ## Pixel-look
 
 To enforce pixelated theme:
@@ -79,8 +126,11 @@ To enforce pixelated theme:
 
 ## Building from source
 
-`SixLabors.ImageSharp` is the only required third-party package
-and happens to be well-supported on both Linux and macOS. It's used for producing output images in PNG format
+Both third-party packages
+- `SixLabors.ImageSharp` for png and gif generation
+- `MoonSharp` for Lua scripting support
+
+are be well-supported on Windows, Linux and macOS.
 
 ---
 
@@ -93,9 +143,9 @@ Build command for .NET is
 > dotnet publish -c Release -r \<rid\> \<args\>
 
 There are generally two ways to build into an executable:
-1. Self-contained exe. This dll is SILK.NET native dependency and needs be included
-    - larger executable (~37 MB on Windows, ~39 MB on Ubuntu) but runs on its own, no .NET runtime installation 
-    required for end user
+1. Self-contained executable
+    - larger size (~37 MB on Windows, ~39 MB on Ubuntu) but runs on its own, no .NET runtime installation 
+    required from end user
 2. minimal exe + DLLs 
     - very small, but end user must have **.NET 10.0 Runtime** installed
 
@@ -161,18 +211,28 @@ copy-pasting all the colors)
 - maybe depth of field/blur in some form
 - materials/mediums: glass, matte, lambertian, fog/gas
     - maybe also simplistic emissive materials
-- objects:
+- geometry:
     - simple meshes for custom shapes. Also some kind of preview tool could be useful
     - maybe some new primitives
     - maybe new transforms like shear
+- shared materials (and meshes): current system adds materials in each object, prevent reusing them
 - performance 
     - at least BHV when meshes get added
     - otherwise some smaller optimizations here and there
-- scripting support via Lua language (complex scenes + animations)
-- more unit tests + maybe a few integration tests
+- scipting: add lights (transforms and camera controls already there)
+- more tests
 
 #### Priority
-1. Lua scripting support
+1. light manipulation in scripts
 2. meshes + BHV
 3. new materials/mediums
-4. the rest
+4. shared materials and meshes
+4. the rest
+
+
+TODO:
+
+- scripting: custom frame count
+- Lua: add light support
+- make a basic animation, add it into scene (along with scene.json)
+- update README: add Scripting section

docs/Images/defaultGif.gif

@@ -0,0 +1,134 @@
+**This document is about creating scripts to produce dynamic scenes**.
+
+**You still need a static scene file for initial state. If you don't have one, see [Scene.md](Scene.md)**
+
+**Scene and script file templates used for producing README image + gif can be in [scene-template](../scene-template/) directory**
+
+
+## How to
+
+- create a scene json file
+- for objects you want to manipulate: add `name` field and add identifier e.g. `"name": "sphere1"`
+- write a script in Lua format
+- use `PixelRay -i <scene> -s <script> <frames> -g` to produce frames and combine them into a gif
+
+## Lua API
+
+`camera` is for camera access, you can manipulate
+- position (`camera:Position`)
+- look direction (`camera:LookAt`)
+- upward axis (`camera:Up`)
+- field of view (`camera:Fov`)
+- aspect ratio (`camera:AspectRatio`)
+    - no internal calculation are performed so this just a raw value
+
+`scene` can be used to access the scene itself
+
+- To access an object instance, use `GetObject(name)` and store reference to a variable:
+
+    ```lua
+    obj = scene:GetObject("torus1")
+    ```
+
+    You should use a descriptive name, especially in complex scenes:
+
+    ```lua
+    torus1 = scene:GetObject("torus1")
+    ```
+
+Currently only transforms can be manipulated.
+
+### Transforms
+
+#### Order of operations (IMPORTANT)
+
+For static scenes, PixelRay will always perform translation in this order:  
+    
+    scale -> rotate -> translate
+
+Reason is that all geometry objects primitives are origin-centered so matrix transforms behave as expected.
+
+**What this means for animations:**
+
+- translations work always
+- scaling and rotating: 
+    - requires you to translate object into origin (0, 0, 0)
+    - then perform scaling and/or rotating
+    - then translate back to actual position
+
+    For example: object at (1, 0.5, -2), you want to scale it. You then first move to (0, 0, 0) by applying inverse translation (-1, -0.5, 2) then scale, then apply translation (1, 0.5, -2) again.
+
+**It's important to follow this principle, otherwise your animations will not produce correct frames.**
+
+---
+
+#### Transform commands
+
+- `ResetTransform()`  
+    Resets object back to base transformation defined in json scene file
+
+    - this is good for parametric equations: instead of using previous state, reset back to initial then let **t** define new state
+    - it also good to use this for stability purposes: long animations require stacking lots of transformations -> lots of matrix multiplication -> possible numerical instability
+
+    **Example:**
+    ```lua
+    obj:ResetTransform()
+    ```
+
+- `Translate(x, y, z)`  
+    Move object to new position along vector (x, y, z) from current position
+
+    - this doesn't move you TO position (x, y, z), but rather adds the vector so you move along it's direction and magnitude (= summing two vectors)
+    
+    **Example:**
+    ```lua
+    obj:Translate(1, -3, 1)
+    ```
+
+    Here, if `obj` current position is (1, 2, 3), `obj:Translate(1, -3, 1)` moves it to (2, -1, 4)
+
+- `Scale(x, y, z)`  
+    Scale each object axis individually
+
+    **Example:**
+    ```lua
+    obj:Scale(0.5, 1, 1)
+    ```
+
+    Scales object in x-direction to 0.5, others stay unchanged
+    
+- `ScaleUniform(t)`  
+    Scale all axes equally
+
+    **Example:**
+    ```lua
+    obj:Scale(0.5)
+    ```
+
+    This is same as using `obj:Scale(0.5, 0.5, 0.5)`
+
+- `Rotate(x, y, z, w)`  
+    Rotate object with respect to axis direction (x, y, z) using angle w (in degrees)
+
+    **Example:**
+    ```lua
+    obj:Rotate(0, 1, 0, 90)
+    ```
+
+    This would rotate object around y-axis for 90 degrees
+
+- `RotateMultiple(r1, r2, ...)`  
+    Apply multiple rotation one after another
+    - useful for complex rotations: instead of calculating final rotation, you can progress step by step
+    - uses Lua tables {x1, y1, z1, w1} to separate rotations
+
+    **Example:**
+    ```lua
+    obj:RotateMultiple({1, 0, 0, 90}, {0, 1, 0, 90}, {0, 0, 1, 90})
+    ```
+    
+    This would first perform 90 degree x-direction rotation, then same for y-direction and finally for z-direction. In this case, outcome is same as a single (0, 1, 0, 90) rotation.
+
+
+
+

docs/Lua.md

@@ -1,4 +1,4 @@
-## Right-hand coordinates:
+ ## Right-hand coordinates:
 - standard: 
     - x increases to right, y increases upwards, camera points to negative z-axis
     - `lookAt = (0, 0, -1)`, `up = (0, 1, 0)` matches to this system
@@ -31,7 +31,7 @@ Here are all the scene entities and their parameters
 
 #### render
 
-- `threading`: `boolean, default=false` 
+- `threading`: `boolean, default=true` 
     - for parallelized rendering
 - `width`: `integer >= 0` 
     - image width
@@ -73,7 +73,8 @@ Here are all the scene entities and their parameters
 
 ### Objects
 
-#### primitives:
+Each object has optional `name` field. This can be used for accessing specific object in Lua scripts.
+
 - `sphere` unit sphere
 - `disc` unit disc pointing at (0, 1, 0)
 - `plane` plane pointing at (0, 1, 0)
@@ -93,8 +94,9 @@ Here are all the scene entities and their parameters
 Use transforms to change object geometry, and materials to change color & how light is reflected
 
 #### transforms
-- `position`: `[x, y, z]` 
-    - translation/shifting/moving object position
+- `translate`: `[x, y, z]` 
+    - translation/shifting/moving object position alongside vector (x, y, z)
+    - it doesn't move object TO (x, y, z), instead adds this vector to your current position
 - `rotation`: `list of [x, y, z, w]` 
     - 4D vector [x, y, z, w] where (x,y,z) is the rotation axis and w the angle in degrees (not radians!)
     - rotations are always treated as a list of rotations so even for a single rotation, use `[[1, 0, 0, 90]]`. If no 
@@ -216,7 +218,7 @@ For radius types:
         "fov": 90
     },
     "render": { // renderer configurations
-        "threading": true, // default is 'false', but keep this enabled for major rendering speed boost (unless very old cpu)
+        "threading": true, // default is 'true' so this line is unnecessary. Keep enabled for major rendering speed boost
         "width": 250,
         "height": 140,
         "upScaleFactor": 3,
@@ -293,6 +295,7 @@ For radius types:
             }
         },
         {
+            "name": "torus1" // optional name, useful for referring to specific objects when scripting
             "type": "torus",
             "minorRadius": 0.2,
             "majorRadius": 0.1,