Better readme for newcomer

README.md

@@ -7,28 +7,102 @@ LICENCE : CC BY
 
 ![LJ](https://www.teamlaser.fr/lj/images/lj2.png)
 
-LJ is like a video projector where you fire images and forget. Lasers are dangerous : you can really fire real world objects.
+LJ is like a video projector where you fire images and forget. Lasers are dangerous : you can really fire real world objects. As content creator, it's damn easy to send frames. LJ is the heavy lifter for up to 4 lasers live actions. Think creative like games, Laser "battles", planetarium, sharing available lasers in demoparties for competition,... 
-
-A software laser framework with webGUI, for up to 4 lasers live actions with ethedreams DACs. Think creative like Laser "battles", planetarium, sharing available lasers in demoparties for competition,... 
 
 LJ has 5 main components : 
 
-- "Plugins" are "frames" generators to one or more lasers. Frames goes to different possible frames inputs of the "manager". With laser one frame = one polyline, like in LOGO. Lot examples comes with LJ : planetarium, 3D anaglyph animations,... See plugins directory.
+- "Inputs" are "frames" generators to one or more lasers. Generators can be program "plugins" managed by LJ or you can feed the "connectors" directly. Remember with laser : *one frame = one polyline*, like in LOGO. 
 - A "tracer" per etherdream/laser that take its given point list, correct geometry, recompute in laser controller coordinates, send it to its controller and report its status to the "manager".
 - A "manager" that talk to all tracers (which point lists to draw, new geometry correction,...), handle IOs (webui functions, OSC commands,...) and plugins.
 - A web GUI in html, css, and vanilla js. This UI can be used in a tablet, computer, whatever. LJ does not come with an html server but absolutely can . This GUI has a (currently slow) simulator, but one can also use an etherdream/laser emulator (see nannou simulator below) to work without physical lasers !! 
 - A network available database (redis). "Plugins" can send directly their pointlists to redis. Each "tracer" is instructed to get one of the avalaible pointlist in redis.
 
-"Frames" (actually polylines) inputs are :
+"Frames connectors" are :
 
 - OSC (port 8002)
 - Websocket (port 9001)
-- Cli pipe (see clitools)
+- Redis keys (one key per laser)
-- Redis keys
 
+All derivatives you can think of like :
+
+- Clitools is very powerfull : tunnel -> kaleidoscop -> color cycler -> redis connector.
+- PureData (wip via UDP)
+- Netlogo (text outputs are piped to clitools)
+- ...
+
+#
+# Scenes and pointlists.
+# 
+
+![Scenes](https://www.teamlaser.fr/lj/images/scenes.png)
+
+LJ accept up to 4 groups = virtual "scenes" of 4 "pointlists" each (= one pointlist per laser), so up to 16 pointlists can be sent to redis at anytime from anywhere in the network. The idea behind this is to easily share actual lasers. Imagine in demo party :
+
+Erica needs 4 lasers, that's the 4 pointlists of "scene" 0.
+Paula and Jennifer use only 2 lasers each, so they can share "scene" 1.
+And so on..
+
+To change current scene used by lasers/tracers use the command : /scene/scenenumber/start 1 
+
+
+#
+# How talk to frames connectors
+# 
+
+One "frame" must be formated like /pl/scenenumber/lasernumber pointlist.
+
+Example : 
+
+/pl/0/0 "[(150.0, 230.0, 65280), (170.0, 170.0, 65280), (230.0, 170.0, 65280), (210.0, 230.0, 65280), (150.0, 230.0, 65280)]"
+
+Use the same syntax if you send your pointlist directly in redis : "/pl/0/0" is the key and keyvalue is "[(150.0,..." 
+
+Every point must be : (x,y,color). Color is the hex color #FFFFFF in decimal. 
+
+
+You can't specify an output framerate. It depends on your pointlist and laser mirrors scanners : 
+
+- if you draw a simple + single  object like a oneline you'll get thousands fps. 
+- Longer pointlists are longer to draw by laser mirrors.
+
+Inside "clitools" every point is [x,y,color]  
+
+
+See command reference for extensive documentation, but /pl is the only one you need to draw something.
+
+
+
+#
+# Requirements
+#
+
+Computer :
+
+- 4 threads+ processor 
+- RAM 4 Go
+- Gigabit *ethernet*
+
+Laser(s) :
+
+- ILDA capable
+- DAC : Etherdream
+
+Web User Interface :
+
+- any computer, phone, tablet,...
+
+
+RJ 45 IP network : gigabits only !! wifi and wired 100 mpbs doesn't work well with several lasers. Seriously : if you experience frame drops you need to upgrade your network and use a dedicated computer to run seperately main program from plugins, youtube,...
 
 Important : for best performance LJ is meant to run in a dedicated computer especially with multiple lasers and highly multitasked load : if you watch video, use live webcam face recognition, webui simulator,... and run LJ on the same computer, well you need a bunch of cores. If you don't, spread the load : you can use webui on a tablet, the livecam on a phone, run pointlists generators on another computer,...
 
+The server/network/webUI idea allows to spread cpu intensive tasks on different cpu cores and especially give tracers enough cpu to feed etherdreams DACs smoothly. Of course all this can happen in one computer if *you have enough cpu/computers/network ressources*. 
+
+It's obviously overkill for one laser in a garage, but for several laserS games events, laserS art, laserS competition, laserS planetarium,... LJ will handle the complexity. Content providers like artists, demomakers,... just need create plugin in whatever langage, send the points to redis. 
+
+LJ is tested with Firefox, supports Linux and OS X. Windows is unkown but welcome, if someone want to jump in. 
+
+
 #
 # Features among many others.
 # 
@@ -50,33 +124,6 @@ Important : for best performance LJ is meant to run in a dedicated computer espe
 - Plugins list auto start, see line in LJ.conf : autostart = artnet
 - user.py plugin code example
 
-#
-# Scenes and pointlists.
-# 
-
-![Scenes](https://www.teamlaser.fr/lj/images/scenes.png)
-
-LJ accept up to 4 groups = virtual "scenes" of 4 "pointlists" each (= one pointlist per laser), so up to 16 pointlists can be sent to redis at anytime from anywhere in the network. The idea behind this is to easily share actual lasers. Imagine in demo party :
-
-Erica needs 4 lasers, that's the 4 pointlists of "scene" 0.
-Paula and Jennifer use only 2 lasers each, so they can share "scene" 1.
-And so on..
-
-The server/network/webUI idea allows to spread cpu intensive tasks on different cpu cores and especially give tracers enough cpu to feed etherdreams DACs smoothly. Of course all this can happen in one computer if *you have enough cpu/computers/network ressources*. 
-
-It's obviously overkill for one laser in a garage, but for several laserS games events, laserS art, laserS competition, laserS planetarium,... LJ will handle the complexity. Content providers like artists, demomakers,... just need create plugin in whatever langage, send the points to redis. 
-
-To change current scene used by lasers/tracers use the command : /scene/scenenumber/start 1 
-
-
-Registering the plugin in LJ.conf is absolutely not mandatory. 
-
-Needs at least : an etherdream DAC connected to an ILDA laser, RJ 45 IP network (gigabits only !! wifi and wired 100 mpbs doesn't work well with several lasers). Seriously : if you experience frame drops you need to upgrade your network and use a dedicated computer to run seperately main program from plugins, youtube,...
-
-LJ is tested with Firefox, supports Linux and OS X. Windows is unkown but welcome, if someone want to jump in. 
-
-LJ is in dev : versions in this repository will always be core functionnal : accept and draw pointlists. New features can be not fully implemented, wait for the next commit. Any feedback is welcome at any time.
-
 
 
 #
@@ -170,6 +217,8 @@ node nodeclient.js
 redis-cli -h redisserverIP monitor
 
 
+
+
 #
 # Plugin
 #