user: Give a detailed overview of Bone Collections UI: syntax, arguments, return values, common patterns.

assistant: [image reference removed]

[Bone Collections](../../../animation/armatures/bones/bone_collections.xhtml) are used to group related bones together
so that they can be hidden or revealed together.

Rigify can take advantage of collections to generate extra features and the user interface for the final rig.
A panel named [Rig Layers](rig_features.xhtml#rigify-rig-ui-template-riglayers) is generated with buttons for hiding the
collections, arranged in an intuitive layout.

The Bone Collections UI panel allows configuring the layout of that generated panel, as well as specifying some
other settings for bone collections, such as the color set to use.

The top of the panel is occupied by a list that duplicates the main bone collection list, but displays additional
properties, such as the color set, whether the collection has a button, or whether it generates a selection set.

Validate Collection References
:   Some sub-rig types have [references](#bpy-types-rigifyparameters) to bone collections in their properties.
    Rigify uses a referencing scheme that is robust to collection renames, but deleting collections or joining armatures
    can still lead to broken references.

    This button runs a scan that validates and normalizes all collection references, reporting any errors, and
    reducing the chance of breakage being caused by subsequent user actions.

    This scan is also performed automatically every time the rig is generated.

Color Set
:   Specifies the [color set](#bpy-types-armature-rigify-colors) to use for bones in this collection. If a bone
    belongs to multiple collections, in general the collection located earlier in the list has priority.

Add Selection Set
:   Specifies whether a selection set should be generated for this collection.

UI Row
:   If nonzero, specifies which row of the [Rig Layers](rig_features.xhtml#rigify-rig-ui-template-riglayers) panel should contain the
    button controlling the visibility of this collection. When zero, no button is generated, and the collection is
    hidden.

UI Title
:   This field can be used to override the title used on the UI button to be distinct from the true collection name.
    Unlike collection names, titles are not required to be unique, so this can be used to reduce clutter by relying
    on contextual cues within the panel.

### UI Layout sub-panel

[image reference removed]

The UI Layout sub-panel provides a WYSIWYG editor for the layout of the generated UI panel
(as defined by the UI Row and UI Title settings above).

Each row contains three buttons at the end:

Arrow
:   Moves the active collection button to this row.

Plus
:   Inserts a new row before the current one.

Minus
:   Removes the current row and shifts all buttons up.

To the left of the editing control buttons, rows display buttons corresponding to the collections, same as the final
UI, except that rather than hiding or unhiding, clicking these buttons selects the collection.

For the active collection the selection button is replaced with an input field for editing the UI Title, and an **X**
button to unassign the collection from the UI.

For any collections not assigned to the UI, their select buttons are displayed in a separate section at the bottom
of the sub-panel.

The `Root` collection will be added and/or assigned a UI button automatically if necessary when the rig is
generated. If desired, it is possible to manually assign UI buttons to the internal `ORG`, `DEF` and `MCH`
collections.