Notifier

From Terragen Documentation from Planetside Software
Jump to: navigation, search

Notifier.gif

Node Description & Purpose:
The Notifier node is intended to be used for helping to debug function node networks. It allows you to see the values being output from nodes or to show a message when some user defined event happens.

You control when the node sends notifications with the Trigger input. The notification will be sent if the Trigger input is a value other than zero. There are many ways you could cause a notification could be triggered. For example, you could use a Conditional scalar to check if a value was greater than 1.0. Hook a constant scalar set to 1 up to the Conditional's If result input and then if the input value was greater than 0.5 one would be sent to Notifier node to trigger the message. Here's what that might look like in the node network:

Notifier-trigger-example.jpg
[trigger example]


This is a bit of a contrived example, but it shows how you might set things up. In this case we adding together two Constant scalar nodes and using the result for the Luminosity value of Surface layer 01. The Add scalar node also has its output connection to the Conditional node. The Conditional node is using a constant 0.5 for its comparison value, and a constant 1.0 for its If result. Its Condition setting is set to Greater than. The output of the conditional is connected to the Trigger input of the Notifier. If the value of the Add scalar node is greater than 0.5 then 1.0 is sent to the Notifier, and because that's not equal to zero a notification will be sent.

The node can be set to notify only during full renders, or also for 3D preview rendering (henceforth just called preview rendering). When notifying you during preview renders you can expect there to potentially be a lot of notifications, perhaps too many to be manageable.

During full renders the node needs to be part of the main network to work. This is not the case during preview renders. In the Trigger example above, the node is not connected into the main network. However, if we were to just connect the Notifier node into the main network between the Add scalar node and the Surface Layer node then notifications can be sent during a full render. This is what that would like:

Notifier-trigger-example-co.jpg
[Notifier connected into the main network]


The node always outputs the value that comes into the Input connection, whether it is a colour, scalar or vector. This effectively makes the node transparent to the network, so you can hook it in anywhere and it won't effect the network. In the screenshot above the Notifier node has no effect on the values flowing between the Add scalar 01 node and the Surface layer 01 node.

There are four different notification methods. You can use any combination of these you like. The simplest notification is just a beep. The three other methods display messages you enter in different places. You can have a message shown in the Errors and Warnings window, the console or written to a file that you specify. On Windows you will need to be using the command line version of the application to see console messages, they get displayed in the command line window. On OS X the messages are printed to the console log, which can be view using the Console application found in the Utilities folder in your Applications folder.

The node has three inputs for a colour, scalar or vector. You can display these values in the notification messages by using specially formatted message text. As a quick introduction let's say you have a node connected to the Scalar input. To show the Scalar value you could enter the following text in any of the message fields:

Scalar value = $SCAL

If the Scalar value was 10.5, this is the message the node would display:

Scalar value = 10.5

Notice the "$SCAL" in the message text. This is a special token which tells the node to look at the value of the Scalar input and then substitute the "$SCAL" token in the message text with the Scalar value.

Here is a list of the tokens supported by the node, with output examples:

Colour tokens
$COL# Outputs the Colour value, showing all colour components - rgb=1, 0.5, 0
$COLR Outputs the red component of the Colour value - r=1
$COLG Outputs the green component of the Colour value - g=0.5
$COLB Outputs the blue component of the Colour value - b=0

Scalar tokens
$SCAL Outputs the Scalar value - 10.5

Vector tokens
$VEC# Outputs the Vector value, showing all coordinates - xyz=0, 10.9, -100
$VECX Outpus the x coordinate to the Vector value - x=0
$VECY Outpus the y coordinate to the Vector value - y=10.9
$VECZ Outpus the z coordinate to the Vector value - z=-100

Special tokens
$NAME Outputs the name of the Notifier node - Notifier 01
$NEWL Outputs a new line, or line break. Any further message text will appear on a new line.

Just a note on those last two tokens. The $NAME token can be very useful for distinguishing between multiple Notifier nodes. Use of the $NEWL token for warning messages isn't recommended, as the Errors and Warnings dialog only displays one line of text for each warning. Any text on a new line may not be visible.

Here's a complex example of using the tokens in message text:

$NAME: col - $COL# $COLR $COLG $COLB / scalar - $SCAL $NEWLvec - $VEC# $VECX $VECY $VECZ

This is what the displayed message text will look like with the following input values:

Node name = Notifier 01
Colour = 1, 0.2195, 0.0104
Scalar = 2.75
Vector = 0, 10, 100

Here is the displayed message text:

Notifier 01: col - rgb= 1, 0.2195, 0.0104 r=1 g=0.2195 b=0.0104 / scalar - 2.75
vec - xyz= 0, 10, 100 x=0 y=10 z=100

You can see that the $NEWL token has broken the text into two lines.

If you add a token to the message text for, let's say, a scalar but there isn't a node attached to the Scalar input, then you will see "???" substituted in the displayed message text instead of a scalar value. Going to back to the very first formatted message text example above, this is what you would see if there wasn't anything connected to the Scalar input:

Scalar value = ???

Node Type: Function

Settings:

  • Only enable during full renders: If this is checked then the Notifier will only perform notifications during full renders. If it's unchecked notifications will happen whenever the 3D Preview is rendering, and this can produce an overwhelming number of notifications. Please note that for the Notifier to work during full renders it needs to be hooked into the main network, as discussed above.
  • Trigger input: This is the input that tells the Notifier when to send a notification. If the value of this input is not equal to 0 then a notification will be performed.
  • Colour input: The Notifier will read the value from this input as a colour. The colour value can then be displayed in the notification by using the colour tokens in the message text, as discussed above.
  • Scalar input: The Notifier will read the value from this input as a scalar. The scalar value can then be displayed in the notification by using the scalar tokens in the message text, as discussed above.
  • Vector input: The Notifier will read the value from this input as a vector. The vector value can then be displayed in the notification by using the vector tokens in the message text, as discussed above.
  • Beep: If this is checked the Notifier will been when it's triggered.
  • Show warning message: If this is checked the Notifier will post a warning message to the Errors and Warnings window. The warning message will also be displayed in the console. The text of the warning is set in the Warning message field below.
  • Warning message: This is where you enter the text for the warning message. You can use the special tokens described above in this text.
  • Write message to console: If this is checked the Notifier will write a message to the console. To see the message on Windows you will need to be using the command line version of TG2, as they get written to the command line window. On Mac OS X the messages are printed to the console log, which can be viewed using the Console application found in the Utilities folder in your Applications folder. The text of the message is set in the Console message field below.
  • Console message: This is where you enter the text for the console message. You can use the special tokens described above in this text.
  • Write message to file: If this is checked the Notifier will write a message to the file you choose below. The text of the warning is set in the Message to write field below.
  • File: This is where you choose the file the message gets written to. New messages are always added after the last line in the file (i.e. they're appended to the file). The size of the file can grow quickly if a lot of messages are being written to it.
  • Message to write: This is where you enter the text for the message written to the file specified above. You can use the special tokens described above in this text.

A scalar is a single number. 1, 200.45, -45, -0.2 are all examples of scalar values.

A single object or device in the node network which generates or modifies data and may accept input data or create output data or both, depending on its function. Nodes usually have their own settings which control the data they create or how they modify data passing through them. Nodes are connected together in a network to perform work in a network-based user interface. In Terragen 2 nodes are connected together to describe a scene.

A vector is a set of three scalars, normally representing X, Y and Z coordinates. It also commonly represents rotation, where the values are pitch, heading and bank.