Namespace:
Autodesk.Revit.DB
Assembly:
RevitAPI
(in RevitAPI.dll) Version: 21.0.0.0 (21.1.1.109)
Since:
2015
Syntax
Remarks
Each NumberingSchema controls numbering of elements of one particular kind, typically of the same category such as Rebar or Fabric Reinforcement. Instances of NumberingSchema are also elements and there is always only one of each type in every Revit document. Available types of all built-in numbering schemas are enumerated in NumberingSchemaTypes class. At present, schema elements cannot be manually added, deleted, or copied. Attempts to do so will result in a failure warning and/or exceptions thrown.
Elements (e.g. Rebar) belonging to a particular schema (e.g. NumberingSchemaTypes.StructuralNumberingSchemas.Rebar) are organized and numbered in sequences. A sequence is a collection of elements that share the same numbering partition as defined by their respective values of the Partition parameter (NUMBER_PARTITION_PARAM). For a numbering sequence to exist it must contain at least one element. In other words, a sequence is established once there is at least one element of which the partition parameter has a value that differs from other elements (in the same numbering schema). If the last element is removed (deleted or moved to a different sequence) the then empty sequence ceases to exist.
Elements get assigned to sequences either upon their creation (based on the then current numbering partition value), or by explicitly modifying the Partition parameter of an element, or by using the AssignElementsToSequence method. It is highly recommended using that method over explicitly changing the Partition parameter, because the methods applies changes to sequences and element numbers immediately, while changed parameters get into effect only after the current transaction is closed.
In addition to directly or indirectly changing the Partition parameter of elements, numbering sequences can be reorganized by using methods of the NumberingSchema class. The MoveSequence method moves all elements of an existing sequence to a new sequence that does not exist yet in the schema, thus effectively renaming the Partition parameter on all the affected elements. The AppendSequence method removes all elements from one sequence and appends them to elements of another existing sequence while applying the matching policy. The method MergeSequences takes elements of all specified sequences and moves them all into a newly created sequence. All the merged elements will be renumbered and matched as needed based on the matching algorithm.
Elements in different sequences are numbered independently, meaning that there may be elements with the same number in two sequences even though the elements are different. Likewise, there may be perfectly identical elements in two or more sequences bearing different numbers. However, within each one numbering sequence any two identical elements will always have the same number, while different elements will never have the same number within a numbering sequence. Revit refers to this rule as the matching policy.
Enumerable elements are always numbered automatically upon their creation. Each new element will get an incrementally higher number. However, thanks to the matching policy, new elements that match existing elements within the same sequence will get the same number assigned. Elements will keep their assigned numbers as long as it is possible. This means, for example, that if some previously created elements (e.g. Rebar) get deleted, all remaining elements (within the same numbering sequence) will keep their numbers, which may result in gaps in the respective numbering sequence. Gaps can be removed by invoking RemoveGaps for sequences in which gaps are not desired.
Numbers are stored as values of a numbering parameter on each numbered element. The Id of the parameter is obtained by querying the NumberingParameterId property. The value of the number can be obtained by querying the parameter for the respective numbered element. The value is read-only and thus cannot be set; it is always computed based on relations of elements across numbering partitions and the matching policy within the numbering sequence of each element.
Even though numbers are always assigned automatically to all elements of a schema, the method ChangeNumber gives the programmer a way to explicitly overwrite a specific number as long as the new number is unique in the numbering sequence. The caller specifies a number to be changed and a new value that is to be applied, providing the value does not exist yet in the same numbering sequence. Although this operation may seem rather limited, it provides the programmer with freedom to change practically any number even if it may be achieved in multiple steps.
Examples
/// <summary>
/// This function consolidates the numbers on Rebar elements by removing
/// any remaining gaps in numbering sequences and setting the start number
/// of each sequence so numbers in sequences do not overlap.
/// </summary>
/// <param name="document">The document in which Rebar numbers are to be consolidated</param>
private void ConsolidateRebarNumbers(Document document)
{
// Obtain a schema object for a particular kind of elements
NumberingSchema schema = NumberingSchema.GetNumberingSchema(document,NumberingSchemaTypes.StructuralNumberingSchemas.Rebar);
// Collect the names of partitions of all the numbering sequences currently contained in the schema
IList<string> sequences = schema.GetNumberingSequences();
using (Transaction transaction = new Transaction(document))
{
// Changes to numbers must be made inside a transaction
transaction.Start("Consolidate Rebar Numbers");
// First we make sure numbers in all sequences are consecutive
// by removing possible gaps in numbers. Note: RemoveGaps does
// nothing for a sequence where there are no gaps present.
// We also want to find what the maximum range of numbers is
// of all the sequences (the one the widest span of used numbers)
int maxRange = 0;
foreach (string name in sequences)
{
schema.RemoveGaps(name);
// Here we use First() from the Linq extension.
// There is always at least one range in every sequence,
// and after gaps are closed there is exactly one range.
IntegerRange range = schema.GetNumbers(name).First();
int rangeSpan = 1 + (range.High - range.Low);
if (rangeSpan > maxRange)
{
maxRange = rangeSpan;
}
}
// Next we give sequences different start numbers
// starting with 100 and then stepping by at least
// the maximum range we found in the previous step
int startNumber = 100;
// We round the range up to the closest 100
int step = 100 * (int)((maxRange + 99) / 100.0);
foreach (string name in sequences)
{
schema.ShiftNumbers(name, startNumber);
startNumber += step;
}
transaction.Commit();
}
}
''' <summary>
''' This function consolidates the numbers on Rebar elements by removing
''' any remaining gaps in numbering sequences and setting the start number
''' of each sequence so numbers in sequences do not overlap.
''' </summary>
''' <param name="document">The document in which Rebar numbers are to be consolidated</param>
Private Sub ConsolidateRebarNumbers(document As Document)
' Obtain a schema object for a particular kind of elements
Dim schema As NumberingSchema = NumberingSchema.GetNumberingSchema(document, NumberingSchemaTypes.StructuralNumberingSchemas.Rebar)
' Collect the names of partitions of all the numbering sequences currently contained in the schema
Dim sequences As IList(Of String) = schema.GetNumberingSequences()
Using transaction As New Transaction(document)
' Changes to numbers must be made inside a transaction
transaction.Start("Consolidate Rebar Numbers")
' First we make sure numbers in all sequences are consecutive
' by removing possible gaps in numbers. Note: RemoveGaps does
' nothing for a sequence where there are no gaps present.
' We also want to find what the maximum range of numbers is
' of all the sequences (the one the widest span of used numbers)
Dim maxRange As Integer = 0
For Each name As String In sequences
schema.RemoveGaps(name)
' Here we use First() from the Linq extension.
' There is always at least one range in every sequence,
' and after gaps are closed there is exactly one range.
Dim range As IntegerRange = schema.GetNumbers(name).First()
Dim rangeSpan As Integer = 1 + (range.High - range.Low)
If rangeSpan > maxRange Then
maxRange = rangeSpan
End If
Next
' Next we give sequences different start numbers
' starting with 100 and then stepping by at least
' the maximum range we found in the previous step
Dim startNumber As Integer = 100
' We round the range up to the closest 100
Dim [step] As Integer = 100 * CInt(Math.Truncate((maxRange + 99) / 100.0))
For Each name As String In sequences
schema.ShiftNumbers(name, startNumber)
startNumber += [step]
Next
transaction.Commit()
End Using
End Sub