PiCompositor

TouchDesigner Asset
Version: 0.1

PiCompositor is a layer-based compositing tool for TouchDesigner.

By adding your TOPs into PiCompositor, you turn them into Layers of a composition, with a variety of parameters and functionalities that you can easily control such as:

-Blending (Opacity, Blend Modes, Masking)
-Transformations (Position, Rotation, Scale)
-Rearranging (Duplicating, Reordering, Hiding/Unhiding)
-Selection (Locking, Selection Sets)
-Preview (Solo mode, Mid-level Composite)

This tool is one of the subtools of PiKit toolkit which is currently under development.

> Scroll down to read the documentation

PiCOMPOSITOR COMP

First thing to know is that each PiCompositor component is a composition (like an empty canvas identical to the 'Document' in Photoshop or 'Composition' in AfterEffects) that has a certain Resolution size, a Background color, and a few other parameters, while holding all the layers you wish to add and returning the final composited result as the OUTPUT.

USER INTERFACE

There are THREE panels within PiCOMPOSITOR interface.

LAYERS LIST: The list of layers (Always visible)
PREVIEW Panel: The dual-screen display of the ACTIVE layer beside compositor's final OUTPUT
PARAMETERS Panel: The panel for setting layers or compositor's parameters

IMPORTING LAYERs

To add your layers, Drag'n'Drop your TOPs onto the LAYERS LIST. You can also add another PiCOMPOSITOR instance as a layer. This way you can make layer groups by nesting multiple PiCOMPOSITORs into a master PiCOMPOSITOR.
! Please note that you can only add TOPs or PiCOMPOSITOR instances.
! CAUTION: Currently the layers are path-dependant. Meaning that if you change the path for any imported layer, the layer's source will go missing and you need to redefine the source TOP via 'Drop to Replace Source' parameter.

SELECTING LAYERs

(LClick) on a layer's name -> Selects a single layer
[ctrl](LClick) on multiple names -> Adds multiple layers to your selection
[up] or [down] keys -> Selects the layer above or below

* Locked layers cannot be selected (--> Read the LAYERS LOCK TAG section)
* You can create multiple selection groups via layers' COLOR tag (--> Read the LAYERS COLOR TAG section)

ACTIVE LAYERs

By selecting each layer, you set them as ACTIVE. When selecting multiple layers, the last one becomes the active layer. You can always check the ACTIVE layer from the name at the PARAMETERS Header.

By activating a layer:
> You can set its parameters from the Parameters Panel
> You can preview the composited view upon that layer from the Preview Panel
* to view the active layer only (SOLO mode), hold down the [alt] key

COMPOSITION SETTINGS

To adjust the composition's OUTPUT settings, first you should activate the compositor, then you can adjust its settings from the PARAMETERS PANEL. You can activate the compositor by one of the following ways:

> (LClick) on the OUTPUT section of the PREVIEW PANEL
> (LClick) on the empty space of the LAYERS LIST
> (LClick) on the 'Name' header on the LAYERS LIST

EXTRACTING LAYERs

You can extract layers from the PiCOMPOSITOR onto your NETWORK_EDITOR - resulting in a selectTOP.
There are two ways to extract a layer:

> Drag a layer from LAYERS LIST and Drop onto NETWORK_EDITOR
> Drag a layer preview from PREVIEW PANEL and Drop onto NETWORK_EDITOR

This extraction comes in two modes:
> COMPOSITED extraction -> selected layer composited downwards at any stage -> Default Drag'n'Drop
> SOLO extraction -> only the selected layer -> Hold [alt] + Drag'n'Drop

VISIBILITY TAGs

The eye icon at the first column on the list, defines the VISIBILITY tag of each layer.

(LClick) on the eye of each layer -> Toggles its VISIBILITY
! if there are multiple layers selected, toggle applies on all of them
(LClick) on 'V' at the columns header -> Toggles the VISIBILITY of ALL LAYERS
(RClick) on the eye of each layer -> Toggles the SOLO mode

* SOLO toggle makes the current layer to be the only visibile layer by hiding all the other layers.
* You can switch back to the previous VISIBILITY state of all layers by RClicking again on the eye icon.
* You can hold [alt] while hovering on any layer in the LAYERS LIST, to temporarily solo-view that layer from PREVIEW PANEL.

LOCK TAGS (Selection Protection)

The lock icon at the second column of the list, defines the LOCK tag of each layer.
When a layer is locked, you CANNOT select, delete, nor change its parameters. However you can still change the VISIBILITY attribute for any locked layer.

(LClick) on the lock -> toggle its LOCK
(LClick) on 'L' at the column's header -> toggles the LOCK of ALL LAYERS

COLOR TAGs (Selection Sets)

Each layer holds a COLOR tag, defined as the colored box in the third column of the list.
These tags help you to create multiple SELECTION SETS or SELECTION GROUPS.

(RClick) on a color tag -> Opens the ColorMenu to change the color tag
* While on the ColorMenu, you can preview each option by holding [alt] and hovering on it.
(LClick) on a color tag -> Selects all the layers sharing the hovering Color Tag

* You can add your own color tags by appending to the 'ColorTags_Table' DAT inside the PiCOMPOSITOR COMP (inside 'UI' annotation).

NAMEs & IDs (Layers identity)

You can reorder any layer by Drag'n'Drop on Layer's Name or number (#)

(LClick) on any layer's Name or ID (#) -> Selects the layer
(LClick) on 'Name' at the column's header -> Deselects all and refreshes the list
(2xClick) on a name in LAYERS LIST -> Edits the name of a layer

BLEND TAGs

(LClick) on any layer's Blend column to change its blend mode from the BlendMenu.
! if there are multiple layers selected, the new Blend applies on all of them.
* While on the BlendMenu, you can preview each option by holding down [alt] and hovering on it.

DUPLICATING LAYERs

The double-square icon at the right side of each layer, duplicates that layer.
! if there are multiple layers selected, the duplication applies on all of them.
* You can also duplicate any layer via a keyboard shortcut: [ctrl + d]

DELETING LAYERs

The red 'X' icon at the right side of each layer, deletes that layer.
! if there are multiple layers selected, the duplication applies on all of them
(LClick) on 'X' at the columns header -> Deletes all the layers

* You can also press on [Delete] key to delete all the selected layers.
! Locked Layers are immune from being deleted.

! CAUTION: Please consider the risks of losing LAYER data as the undo for deleting layers might return unwanted results.
! CAUTION: Deleting any layer source (imported TOP) from outside the PiCompositor will be undoable.

PREVIEW PANEL

* By selecting/activating each layer, the ACTIVE viewer updates by showing the composition upto that layer.

* By holding down, [alt] you can SOLO view the HOVERING layer on LAYERS LIST.
(LClick) on OUTPUT -> Selects the COMPOSITION for adjustments in PARAMETERS PANEL

You can also extract any of the viewers by (LClick) Drag'n'drop from the preview onto NETWORK_EDITOR
(--> Read EXTRACTING LAYERS section)

PARAMETERS PANEL

Here you can adjust the parameters (transform, opacity, blend mode, etc.) for either the SELECTED layers or the main COMPOSITION.

How to access Composition's OUTPUT parameters? -> Read COMPOSITION SETTINGS section ^

* When multiple layers are selected, any changes in PARAMETERS panel will apply on all of them.
* You can copy and paste a layer's parameters via famous Copy/Paste hotkeys [ctrl+c][ctrl+v]

MASKING

You can apply layer masks from outside the PiCompositor by drag and dropping them (as a TOP) into the layer's 'Mask Layer' Parameter. You can also drag (with RClick) another LAYER from the LAYERS LIST onto the active layer's 'Mask Layer' parameter.

! If multiple layers are selected, the new Mask Layer parameter will be applied on all of them.

! CAUTION: Currently masking is name-dependant. So in case you later change the mask source's name or path, you need to redefine the mask in the parameters panel. Hopefully this will be improved in the next version.

* EXTRA TIPS

* To change the default 'Fit' setting for new layers, go to 'I/O' page of PiCOMPOSITOR's main parameters.
* In case the LAYERS LIST stops updating or shows buggy layers, click on the 'Name' header to force cook the list.

[ KEYBOARD HOTKEYS ]

[Ctrl+a] Selects all the layers
[Ctrl+d] Duplicates the selected layers
[Ctrl+c] Copies the active layer's parameters to clipboard
[Ctrl+v] Pastes parameter settings from the clipboard
[Delete] Deletes the selected layers
[up][down] Changes the currently selected layer to the one above or below
Holding [alt] on any list (LayersList, BlendMenu or ColorMenu) helps to temporarily preview that option.

> BUGs

Just like any program, this one comes with bugs and errors as well. so please let me know if you found any via my GitHub page. But before reporting, see what are some of the current bugs that are already existing:

- The most annoying thing about the current version is that the all the layers references are path-dependant. Meaning that if you change the path for any of your layers sources (changing the imported TOPs location in the network editor or changing their parent's name) will cause a MISSING error for the layer that held reference - current fix is that you need to manually redefine the source via the parameter 'Drop to Replace Source'. (-> Read the IMPORTING LAYERs section)

- Similarly, in case you change the NAME for any of the layers that are already refered as a MASK LAYER source for another layer, you need to redefine that mask after renaming. (-> Read the MASKING section)

- Deleting any layer source (imported TOP) from outside the PiCompositor will be undoable.

- In some TD versions (like mine?) there seems to be a small bug with the ListCOMP where it prints a TypeError in TextPort after any keyboard shortcut triggers. However it doesn't seem to interfere with the functions.

> FUTURE DEVELOPMENT

Here are some features that I'm looking to implement for later versions:
+ Reselecting layers (after changing visibility,lock,or blend setting in LAYERS LIST)
+ Merging or Grouping Layers directly within the interface
+ Layer Matting (Masking a layer based on another layer)
+ Multi-layer parameter offseting (currently any change on parameters will apply identical on all the selected layers)
+ Preview panel will be improved
+ Viewer Developments (this is a big one - having your transformations directly within Compositor's Output viewer)
+ Effects list for each layer.

> GOOD LUCK!

That's all folks! Hope you enjoy using this tool.

Feel free to write me an email if you got any questions or suggestions.

In case you wish to support the work, please continue scrolling.

--Documentation--

Ways to Support

As a creative coder who loves building tools alongside creating art, I'm looking forward to not only share some of my useful tools with the community, but also put work on further developing the ones that are already released.

However, as you may know developing these tools comes with a lot of work, time and effort for the best outcome and having little to no financial return, doesn't provide the necessary fuel for the development to run with a convenient pace.

So in case you find this tool useful and you would want to back me on the mission, please support me via buying some of my NFTs or donate any amount digital coin to my Tezos Wallet.

In case you like my arts but you don't necessarily wish to contribute any monetary but community-based value, I'd highly appreciate if you could follow me on Social media (Instagram, Twitter) and share any of my artworks that you like through any ways you wish to spread my voice.

Thank you very much in advance!