.. _omnigraph_naming_conventions:

OmniGraph Naming Conventions
----------------------------
The mandatory naming conventions are noted where applicable. The rest of these conventions have been set up to make it
as easy as possible for you to write your own nodes, and to be able to read the nodes that others have written.

File And Class Names
++++++++++++++++++++
Class and file naming is ``InterCaps`` with the prefix ``Ogn``. For example, *OgnMyNode.ogn*, *OgnYourNode.py*,
*class OgnMyNode*, and *OgnHerNode.cpp*.

As with regular writing, active phrasing (verb-noun) is preferred over passive phrasing when a node name refers to
its function.

+---------------------+--------------------+
| Weak                | Preferred          |
+=====================+====================+
| OgnSumOfTwoValues   | OgnAddTwoValues    |
+---------------------+--------------------+
| OgnAttributeRemoval | OgnRemoveAttribute |
+---------------------+--------------------+
| OgnTextGenerator    | OgnGenerateText    |
+---------------------+--------------------+

.. tip::

     Some of the automated processes use the ``Ogn`` prefix to more quickly recognize node files. Using it helps
     them work at peak efficiency.


Node Names
++++++++++
Although the only real restriction on node names is that they consist of alphanumeric, underscore, or dot characters
there are some conventions established to make it easier to work with nodes, both familiar and unfamiliar.

A node will generally have two names - a unique name to identify it to OmniGraph, and a user-friendly name for viewing
in the UI. The name of the node should be generally related to the name of the class, to make them easy to find.

The name will be made unique within the larger space by prepending the extension as a namespace. The name specified
in the file only need be unique within its extension, and by convention is in uppercase ``CamelCase``, also known as
``PascalCase``. It's a good idea to keep your name related to the class name so that you can correlate the two easily.

.. warning::

    You can override the prepending of the extension name if you want your node name to be something different, but
    if you do, you must be prepared to ensure its uniqueness. To override the name simply put it in a namespace by
    including a `.` character, e.g. `omni.deformer.Visualizer`. Note that the `omni.` prefix is reserved for NVIDIA
    developed extensions.

The user-friendly name can be anything, even an entire phrase, in ``Title Case``. Although any name is acceptable
always keep in mind that your node name will appear in the user interface and its function should be immediately
identifiable from its name. If you do not specify a user-friendly name then the unique name will be used in the user
interface instead.

Here are a few examples from the OmniGraph extensions:

+----------------------+------------------------+-------------------------------------------+----------------------------------+
| Class Name           | Name in the .ogn file  | Unique Extended Name                      | User Facing Node Name            |
+======================+========================+===========================================+==================================+
| OgnTutorialTupleData | TupleData              | omni.graph.tutorials.TupleData            | Tutorial Node: Tuple Attributes  |
+----------------------+------------------------+-------------------------------------------+----------------------------------+
| OgnVersionedDeformer | VersionedDeformer      | omni.graph.examples.cpp.VersionedDeformer | Example Node: Versioned Deformer |
+----------------------+------------------------+-------------------------------------------+----------------------------------+
| OgnAdd               | Add                    | omni.graph.nodes.Add                      | Add                              |
+----------------------+------------------------+-------------------------------------------+----------------------------------+

.. attention::

    The unique node name is restricted to the alphanumeric characters, underscore (``_``), and dot (``.``). Any
    other characters in the node name will cause the code generation to fail with an error message.

Attribute Names
+++++++++++++++
As you will learn, every node has a set of attributes which describe the data it requires to perform its operations.
The attributes also have naming conventions. The mandatory part is that attributes may only contain alphanumeric
characters, underscore, and optional colon-separated namespacing.

The preferred naming for attributes is ``camelCase`` and, as with nodes, both a unique name and a user-friendly
name may be specified where the user-friendly name has no real restrictions.

Attributes have some predefined namespaces depending on their location with the node as well (`inputs:`, `outputs:`,
and `state:`) so you can use this to have inputs and outputs with the same name since they will be in different
namespaces.  Here is an example of attribute names on a node that adds two values together:

+-------------+------------------+
| Full Name   | User Facing Name |
+=============+==================+
| inputs:a    | First Addend     |
+-------------+------------------+
| inputs:b    | Second Addend    |
+-------------+------------------+
| outputs:sum | Sum Of Inputs    |
+-------------+------------------+

.. attention::

    The unique attribute name is restricted to the alphanumeric characters, underscore (``_``), and colon (``:``). Any
    other characters in the attribute name will cause the code generation to fail with an error message.

.. tip::
    
    You will find that use of your node will be easier if you minimize the use of attribute namespaces. It has
    some implications in generated code due to the special meaning of the colon in C++ and Python.
