How Presets are Found by Users

New in version 2.5.0.

As of version 2.5.0, Canvas uses a tagging mechanism to enable discovery of presets. When the user starts typing into the tab search (accessed by pressing the TAB key in the graph view), Canvas searches through the library of presets found by Canvas for the best matches by matching against the tags of each preset.

How Preset Tags are Structured and Applied

Preset tags are organized into categories that correspond to the nature of the tag. A tag is specified as {CategoryName}:{TagText} and is generally presented in the FabricUI in the same way. The set of categories is fixed and is:

ext:{TagText}
For presets that are provided by an extension. For example, presets provided by the Math extension are tagged with ext:Math.
cat:{TagText}
For presets that are part of a “category” of operations a user might want to preform. For example, presets provided by the AlembicWrapper extension are tagged with cat:IO.
aka:{TagText}
For alternative names for presets. For example, the Fabric.Core.Func.Report presets is tagged with aka:Print, aka:Log and aka:Debug.
name:{TagText}
The name of the preset. This tag is automatically applied to presets using the full name of the preset. For example, the preset Fabric.Exts.Math.Quat.SetFrom2Vectors is automatically tagged with name::SetFrom2Vectors.
namecomp:{TagText}
A component of the name of the preset. This tag is automatically applied to presets by breaking the name into component using CamelCase and other obvious work breaks. For example, Fabric.Exts.Math.Quat.SetFrom2Vectors is tagged with namecomp:Set, namecomp:From2 and namecomp:Vectors. This way of breaking into components may not seem quite right but remember that tag searching works on substrings so it actually works well in practice.
pathcomp:{TagText}
Presets are tagged by default with pathcomp:{PathCompoent} for the “path” componets of the preset. For instance, Fabric.Exts.Math.Quat.SetFrom2Vectors is tagged with pathcomp:Quat because of the .Quat. part of the path. Note, however, that this “default” tagging using the path components can be controlled as described below.
porttype:{TagText}
Presets are automatically tagged with the types of their ports (when the types are not polymorphic). For example, the Fabric.Exts.Math.Quat.SetFrom2Vectors preset is tagged with porttype:Vec3 because some of its ports take type Vec3.

Note

Tags are not case-sensitive.

Different tags also carry different weights for search matching. This detail is mostly hidden from the user but is important for the effectiveness of the search. For example, the tags in category porttype:... carry a lower weight (0.8) than the tags in category name:... (1.0) so that the name:... tags will match before the porttype:... tags. This weight can be adjusted for specific tags applied to presets as seen in the section Controlling Tagging of Presets.

A given preset will generally have many tags, some of which are applied automatically and some of which are explicitly specified in the definition of the preset and/or its containing folders or extension. For example, the SetFrom2Vectors preset for the Quat type that comes with the Math extension has the following tags:

  • ext:Math because it is provided by the Math extension.
  • cat:Math because all of the tags in the Math extension are tagged with ext:Math (as described in Controlling Tagging of Presets below).
  • name:SetFrom2Vectors because of its name.
  • namecomp:Set, namecomp:From2, and namecomp:Vectors because of the components of its name.
  • pathcomp:Quat, because of its path components. Note however that it is not tagged with pathcomp:Math because of the config.json file in the $FABRIC_DIR/Presets/DFG/Fabric/Core/Math/ directory, as explained below.
  • porttype:Vec3 because it has ports of type Vec3.

Controlling Tagging of Presets

There are various ways of controlling tagging of presets. Arbitrary tags can be applied to a given preset, all of the presets below a given directory, or all of the presets provided by an extension.

Tagging a Specific Preset

A given preset can be tagged by providing a tags members in the {Preset}.canvas file. For example, the $FABRIC_DIR/Presets/DFG/Fabric/Core/Func/Report.canvas file contains:

...
"tags": [
  "aka:Print",
  "aka:Log",
  "aka:Debug"
  ],
...

Note

the name:... and namecomp:... tags that are automatically applied to presets based on their name are always applied and cannot be controlled or overridden.

Tagging All of the Presets in a Given Directory

All of the presets below a given directory can be tagged by proving a config.json file in that directory that specifies tags. For example, Fabric ships with a $FABRIC_DIR/Presets/DFG/Fabric/Core/Math/config.json file that contains:

{
  "tags": [
    "cat:Math"
    ]
  }

This applies the cat:Math tag to every preset in and below the $FABRIC_DIR/Presets/DFG/Fabric/Core/Math/ directory.

If the config.json file is missing, all of the presets in and below the directory are tagged with pathcomp:{DirectoryName}. For example, if the $FABRIC_DIR/Presets/DFG/Fabric/Core/Math/config.json file were missing then all the presets in or below $FABRIC_DIR/Presets/DFG/Fabric/Core/Math/ would be tagged with pathcomp:Math.

Note

The tags in config.json apply not only to the presets in the directory but also presets in subdirectories, their subdirectories, and so on.

Tagging All of the Presets Provided by an Extension

All of the presets provided by an extension can be tagged by providing a tags section in the extension’s {ExtName}.fpm.json file. For example, the $FABRIC_DIR/Exts/Builtin/Math/Math.fpm.json file contains the text:

...
"tags": [
  "ext:Math",
  "cat:Math"
  ]
...

This applies ext:Math and cat:Math to every preset provided by the Math extension. If there is no tags section in the {ExtName}.fpm.json file then all of the presets provided by the extension are automatically tagged with the single tag ext:{ExtName}.

Note

You must explicitly provide the tag ext:{ExtName} if you have a tags section in {ExtName}.fpm.json. This examples you to omit this tag if is causes issues for some reason, eg. if the extension name is not suggestive of the function of the extension.

Controlling the Weight of Preset Tags

Normally, the default weights that are applied to tags work well, and it is not something that you need to consider. However, it is possible to adjust the weight of a tag as it is applied to a specific preset or to a group of presets in all of the three mechanisms above. To do so, simply specify a weight as {CatName}:{TagText}:{Weight}. For example, if for some reason we wanted the aka::Print tag to applied to the Report.canvas preset with higher weight, we might specify:

...
"tags": [
  "aka:Print:1.5",
  "aka:Log",
  "aka:Debug"
  ],
...