Ai Example

====== Visualiser: Moving RGB Matrix ======

Using Ai to visualise an Artnet-controlled 3D moving matrix, this time with RGB control.

^ by: | Sebastian Beutel, July 2015 |
^ published: | http://www.avolites.de/support-downloads/ai-projekte |
^ tested in version: | made in version 8.0.2, now tested again in 10.2 |
^ download: | {{ :ai:examples:movingrgbmatrix:all_lines.scb |}} patch file (41 MB)|

//Hint: click the images to show them larger.//

This project is based on a similar idea like [[ai:examples:movingmatrix:movingmatrix|]]. However, this time each object is individually RGB-controlled, and a separate window for the RGB mapping is rendered as well.

**It is recommendable to read and understand the other project, before delving into the RGB thing.**

{{tag>visualise 3d moving sculpture matrix rgb artnet}}

{{:ai:examples:movingrgbmatrix:moving_rgb_overview_sm.png?500|}}

===== Background =====

Again we had a moving object to visualise: a matrix comprising of spheres, hung from artnet-controlled winches. This is similar to [[ai:examples:movingmatrix:movingmatrix|]]. However, this time an enhanced product was used where each sphere could be RGB-controlled by Artnet. And when implementing this into the visualisation project in Ai it was decided to also output a flat colour window, to cross-check the programming.

Again, the solution comprises of a multilayer patch, and it made much sense to define the parameters
  * per whole matrix (and for the control window)
  * per line (row)
  * per individual object

It were 20 lines (rows), each comprising of 16 spheres (which again were modeled as cubes for sake of vertices/performance). And the control window was decided to be 400x320 px so that each sphere/cube was represented by a square of 20x20 px.

===== Used Modules and Patches =====

  * [[ai:patches:sample_texture_region_simple]]
  * [[ai:modules:patch:patch_io|]]
  * [[ai:modules:import:3dmorphmodel|]]
  * [[ai:modules:math:vector_join|]]
  * [[ai:modules:controller:constant|]]
  * [[ai:modules:generator:rectangle|]]
  * [[ai:modules:gl:render_to_texture|]]
  * [[ai:modules:gl:render_merge|]]
  * [[ai:modules:network:artnetinputlarge|]]
  * [[ai:modules:math:formula|]]

===== The Patch =====

As like as in [[ai:examples:movingmatrix:movingmatrix|the other example]] this is something for nesting multiple layers of patching - the core is a [[ai:modules:import:3dmorphmodel|]] module, here with coloured texture - and multiple modules are then assembled as groups, some groups make for a line and all the lines create the complete object. This way it's rather easy to only expose the parameters which are really needed to the next level.

==== Unfolding the Patch ====

In order to analyze this project load the patch all_lines.scb (see downloads above) into the stage patch, hook the white ''DMX Sender'' input into the white DMX Sender output on the main Patch IO, and insert a Window, patch it to the yellow ''Output'' port and open it:

{{:ai:examples:movingrgbmatrix:moving_rgb_stagepatch.png?200|Moving RGB Matrix - Stage Patch}} 

The main patch ''all_lines.scb'' offers a couple of parameters to be directly set on its surface:

  * ''X_0'', ''Y_0'' and ''Z_0'' define the overall position of the object in 3D space
  * ''X_Offset'' and ''Z_Offset'' set the spacing between rows and columns of the matrix
  * ''Y_Travel'' sets the max. height travel, i.e. how high the spheres travel between DMX=0% and DMX=100% on the height channel
  * ''Scale'' sets the relative size of the spheres/cubes
  * ''Texture'' is the number of tiles to be rendered in the control window
  * ''Tex_X'' and ''Tex_Y'' define the top-left starting point of the texture in the control window
  * ''Tex_Width'' and ''Tex_Height'' define how large the blocks to be rendered per cube are in the window

Now, let's open all the layers, and find out how this works from  the bottom to the top:

  * double-click on ''all_lines.scb'' to open it
  * this contains 20 subpatches ''1_line.scb'' - double-click on one of them
  * each line consists of 16 subpatches ''1_cube.scb'' - double-click one
  * this opens the patch per individual cube - the core of the project (we don't explain the patch ''Sample Texture Region Simple.scb'' here as this is a factory patch, and [[ai:patches:sample_texture_region_simple|is explained separately]].

==== 1_cube - the inner core ====

{{:ai:examples:movingrgbmatrix:moving_rgb_1_cube.png?300|Moving RGB Matrix, patch per cube}}

Each cube of the final assembly is created in such a patch:
  * the [[ai:modules:import:3dmorphmodel|]] is used to load a suitable model - the easiest variant is the default_cube.3ds (click on ''Load'' and load the file from /Distrib/Models/Default Models)
  * values for ''X Position'', ''Y Position'' and ''Z Position'' are calculated on the layers above, hence the ports are directly wired into the [[ai:modules:patch:patch_io|]] module
  * ''X Scale'', ''Y Scale'' and ''Z Scale'' are all wired into one ''Scale'' port on the Patch IO as they all get the same value
The other modules are used to create the colour from the RGB values, to apply it to the model, and to create a chunk of the final control window
  * [[ai:modules:math:vector_join|]] takes the ''Red'', ''Green'' and ''Blue'' values from the Patch IO, as well as an ''Alpha'' value which is set as [[ai:modules:controller:constant|]], and joins them into one vector
  * this vector is sent as ''Color'' value to the [[ai:modules:generator:rectangle|]]. This directly creates a coloured rectangle video
  * however, in order for the cube to appear coloured we need a texture, not a GL render. Hence, the [[ai:modules:gl:render_to_texture|]] is used. It needs a ''Size Input'' which is a vector, which we create from the ''TexSize'' port of the Patch IO with another Vector Join module. The resulting texture is fed into the ''Texture'' port of the 3D Morph Model, and into the Sample Texture Region's ''Texture In'' port
  * finally, [[ai:patches:sample_texture_region_simple]] creates a tile of our final control window, with the rendered colour. The required parameters ''X Out'', ''Y Out'', ''Out Width'' and ''Out Height'' again come from the Patch IO, and the resulting GL render is sent as ''Output'' to the Patch IO which has the side effect of a closed [[ai:specifics:renderpath|]] to make all other modules behave correctly.

==== 1_line - assembling 16 cubes ====

Going up one level from the single cubes we get to the line patch - this holds 16 cubes as described above, feeding them their parameters:

{{:ai:examples:movingrgbmatrix:moving_rgb_1_line.png?300|Moving RGB Matrix, patch per line}} 
 {{:ai:examples:movingrgbmatrix:moving_rgb_1_line_detail.png?390|Moving RGB Matrix, patch per line - detail}}

The patch ''1_line'' forwards global data from the all_lines patch (top) to the individual cubes (below), and does the Artnet magic. In this case, the assume DMX layout per line/controller is this (derived from an original product):

^ channel ^ description |
| 1 | winch #1 (height) |
| 2 | winch #2 (height) |
| 3 | winch #3 (height) |
| ... | winches #4 ... #20 (height) |
| 21 | red #1 |
| 22 | green #1 |
| 23 | blue #1 |
| 24 | red #2 |
| 25 | green #2 |
| 26 | blue #2 |
| 27 | red #3 |
| ... | colours next pixels |
| 78 | red #20 |
| 79 | green #20 |
| 80 | blue #20 |

(this was originally created with 20 cubes per line which was later reduced to 16).

The input data per cube is produced like this:

  * ''X Position Input'' is the same value for all cubes per line and comes from Patch IO's ''X_0'' port
  * ''Y Position Input'' is calculated from the base height (''Y_0''), plus ''Y_Travel'' * the Artnet height channels value
  * ''Z Position Input'' begins with Patch IO's ''Z_0'' and is incremented by the ''Z_Offset'' per cube
  * ''Scale Input'' is again the same value for all cubes and stems from the ''Scale'' port
  * ''Red'', ''Green'' and ''Blue'' come directly from the respective Artnet channels
  * ''TexSize'' starts with the ''TexSize'' value and decrements per cube object
  * ''X Out'', ''Out Width'' and ''Out Height'' are again global values, patched from Patch IO's ports to all cubes
  * ''Y Out'' is the vertical position of this tile in the control window. It starts at ''Y Out'' and is incremented by ''Out Height'' per cube
  * all the ''Output''s are successively merged together with the [[ai:modules:gl:render_merge|]] modules, and the result returned to Patch IO
  * the ''DMX Send'' is patched to all [[ai:modules:network:artnetinputlarge|]] modules
  * their ''Universe'' port is patched into the Patch IO to allow for easier re-adressing on the higher level

==== all lines - combining 20 lines to a matrix ====

The main patch ''all lines.scb'' holds all 20 lines of cubes, and feeds them their data.

{{:ai:examples:movingrgbmatrix:moving_rgb_all_lines_total.png?250|Moving RGB Matrix, all lines - total view}}  {{:ai:examples:movingrgbmatrix:moving_rgb_all_lines_detail.png?380|Moving RGB Matrix, all lines - detail view}}

The [[ai:modules:patch:patch_io|]] of this module holds only two ports - for data which needs to be patched through to the main stage patch: ''DMX Send'' for the overall ArtNet input which is sent to all lines, and ''Output'' which brings the combined control window to the top (and closes the render path). All other parameters which are seen in the top window are created here as constants (top-left), and right-clicking plus ''Add to Parent Panel'' brings the text inputs at the very top of the project:
  * ''x_0'' sets the left-right start position, hence the first line gets this as ''X_0'', and all subsequent lines are incremented by ''x_Off''.
  * ''y_0'' is the top-down default value which is equal for all lines, and patched to all their ''Y_0'' inputs, as is ''y_Travel'' which sets the maximum travel for DMX=100% on the winch channel
  * ''z_0'' (back-front start position), ''z_Off'' and ''Scale'' are also sent to all lines
  * ''TexSize'' starts with the globally-set value and is decremented by 20 per line
  * ''X_Out'' is the horizontal location in the control window - starts at the globally set value and is incremented by the global ''Out_Width'' which is also forwarded to each line
  * ''Y_Out'' and ''Out_Width'' are both distributed to all lines
  * each line has a designated constant input, to set its universe
  * finally,[[ai:modules:gl:render_merge|]] modules again merge all lines' outputs together, to allow for the finally completed control window output.

===== Application =====

In order to make use of this project import and patch as suggested in [[ai:examples:movingrgbmatrix:movingrgbmatrix#Unfolding the Patch|]] (connect DMX Sender and Output, and open a window). You may adjust the values, and add or delete some elements/subpatches to bring it in line with the project at your hands.