Сообщество программистов Autodesk в СНГ :: Работа с семействами. Загрузка семейства и вставка экземпляра семейства

Сообщество программистов Autodesk в СНГ
Revit API
Работа с семействами. Загрузка семейства и вставка экземпляра семейства

25/12/2013

Работа с семействами. Загрузка семейства и вставка экземпляра семейства

Начнем небольшую серию статей о работе с семействами и с редактором семейств с помощью Revit API.

Рассмотрим два главных аспекта работы с семействами с точки зрения программиста:

Создание семейства. Т.е. работа с редактором семейства.
Использование семейства. В большинстве случаев используются в файле проекта.

Однако вставить семейство можно не только в проект, но и также в другое семейство. Поэтому второй аспект может рассматриваться, как и в контексте файла проекта так и в контексте редактора семейств. В него входят такие задачи как загрузка семейства, вставка экземпляра семейства, работа с типоразмерами и с существующими экземплярами семейств.

Оба этих аспекта являются большими и важными темами для обсуждения, которые мы уже рассматривали ранее.

До Revit 2010 только второй пункт можно было реализовать программно. Программное создание семейства и в целом работа в редакторе семейств была невозможна до появления API для работы с семействами (Family API).

Создание нового семейства с нуля с помощью API подробно описано и продемонстрирован в материалах курса ADN Revit API (на англ.).

Также недавно мы обсуждали как создать и вставить выдавливание в редакторе семейства (на англ.). Тот пример является более легким и простым примером как создать новое семейство и затем вставить его в проект не углубляясь в такие сложные детали как установка выравнивание и создание типоразмеров.

Статьи по API для работы с семействами завершаются списком прошлых тем которые Стив и я решили снова упомянуть:

Загрузка семейства и размещение экземпляров семейства.
Выбор экземпляра семейства в интерфейсе и редактирование экземпляров
Извлечение типоразмеров и экземпляров семейств в проекте, изменение типоразмеров.

В темах также представлены скриншоты кода и готовый проект для Visual Studio содержащий 3 команды, реализующие вышеперечисленные задачи и класс, реализующий интерфейс IExternalApplication, для создания пользовательского интерфейса для удобного запуска этих команд:

CmdTableLoadPlace
CmdTableNewTypeModify
CmdKitchenUpdate

Рассмотрим более подробно реализацию этих команд.

Сейчас мы рассмотрим первую команду, а остальные – в ближайшие несколько дней.

Загрузка семейства и размещение экземпляров семейства

Внешняя команда CmdTableLoadPlace демонстрирует загрузку семейства и размещение экземпляра семейства в проекте.

Перед загрузкой семейства предварительно происходит проверка, не загружено ли уже семейство в проект.

Размещение экземпляра семейства происходит автоматически или получив от пользователя требуемое месторасположение.

В первом случае используется один из множества перегруженных методов NewFamilyInstance для автоматической вставки экземпляра семейства. Подробно мы его обсуждать в рамках данной статьи не будем.

Во втором – метод PromptForFamilyInstancePlacement, с помощью которого пользователь самостоятельно в интерфейсе выбирает месторасположение экземпляра.

Проверяем загружено ли семейство в проект

Перед тем как вставлять экземпляр любого семейства в проект, необходимо загрузить само семейство.

Загрузка в проект семейства, которое уже было загружено ранее, вызовет ошибку, поэтому необходимо сначала проверить, не загружено ли уже семейство в проект.

Всякое извлечение объектов из внутренней базы данных Revit происходит с помощью класса FilteredElementColector. Для наиболее эффективного результата выбора элементов по фильтру, как с точки зрения производительности, так и с точки зрения точности полученных результатов, необходимо задать как можно больше фильтров.

Лучше всего использовать «быстрые» фильтры, так как они позволяют отсеять ненужные элементы без предварительной загрузки элементов в память. «Медленные» фильтры также довольно эффективны с точки зрения производительности, так как проверка свойств и фильтрация происходит в рамках выделенной Revit’у памяти. И самый медленный способ – обработка элементов с помощью кода .NET после того как элементы были извлечены из базы данных Revit.

Предполагая, что в проекте у нас содержится не очень большое количество семейств, мы можем их все получить с помощью фильтра OfClass(typeof(Family)) и затем произвести дополнительную фильтрацию напрямую в .NET с помощью LINQ и стандартного метода FirstOrDefault:

Код - C#: [Выделить]

  FilteredElementCollector a
    = new FilteredElementCollector( doc )
      .OfClass( typeof( Family ) );
 
  Family family = a.FirstOrDefault<Element>(
    e => e.Name.Equals( FamilyName ) )
      as Family;

Поиск элемента по типу и наименованию

Мы уже проверили находится ли семейство в проекте или нет, извлекая все элементы типа Family и получив конкретное семейство по его наименованию.

Такой подход может использоваться с различных видах поиска элементов в Revit, однако всегда необходимо помнить об оптимизации.

В этой надстройке, я сделал фильтрацию как можно проще без какой-либо оптимизации.

Код - C#: [Выделить]

  /// <summary>
  /// Поиск элемента
  /// по его типу и наименованию
  /// </summary>
  public static Element FindElementByName(
    Document doc,
    Type targetType,
    string targetName )
  {
    return new FilteredElementCollector( doc )
      .OfClass( targetType )
      .FirstOrDefault<Element>(
        e => e.Name.Equals( targetName ) );
  }

В надстройке этот вспомогательный метод используется в трех различных случаях:

Поиск конкретного семейства для проверки загружено ли семейство или нет
Поиск типоразмера семейства для проверки есть ли такой типоразмер в проекте или нет
Поиск определённого материала, который необходимо задать типоразмеру

Загрузка семейства

Так как мы уже определили загружено ли семейство в проект или нет, то непосредственно загрузка семейства – довольно простенькая задача:

Код - C#: [Выделить]

  if( null == family )
  {
    // Проверим наличие файла семейства
    // перед загрузкой его в проект
    if( !File.Exists( FamilyPath ) )
    {
      Util.ErrorMsg( string.Format(
        "Проверьте наличие "
        + "файла семейства '{0}' в директории '{1}'.",
        FamilyName, _family_folder ) );
      return Result.Failed;
    }
 
    // Загрузка семейства из файла.
    using( Transaction tx = new Transaction( doc ) )
    {
      tx.Start( "Загрузка семейства" );
      doc.LoadFamily( FamilyPath, out family );
      tx.Commit();
    }
  }

Я добавил дополнительную проверку, что файл семейства действительно существует на диске.

Загрузка семейства изменяет базу данных. Поэтому необходимо наличие транзакции.

Если же семейство содержит большое количество типоразмеров, а вам нужны лишь некоторые из них, то для более эффективного расходования ресурсов и увеличения быстродействия можно загрузить лишь требуемые типоразмеры по очереди с помощью метода LoadFamilySymbol вместо того чтобы загружать семейство целиком с помощью метода LoadFamily.

Размещение экземпляра семейства

Как я уже говорил, мы решили разместить экземпляры семейства вручную. Это легко сделать при помощи метода PromptForFamilyInstancePlacement.

Единственным параметром этого метода является типоразмер (FamilySymbol), экземпляр которого мы хотим поместить в проект.

Код - C#: [Выделить]

  // Определим типоразмер
  FamilySymbol symbol = null;
  foreach( FamilySymbol s in family.Symbols )
  {
    symbol = s;
 
    // Так как наше тестовое семейство содержит только один типоразмер
    // то возьмем первое и выйдем из цикла.
    break;
  }
 
  // Разместим экземпляр выбранного типоразмера:
  // !Метод PromptForFamilyInstancePlacement нельзя  
  // использовать внутри транзакции
  uidoc.PromptForFamilyInstancePlacement( symbol );
 

Получаем доступ к только что созданным экземплярам семейства

Как я уже упоминал, для того чтобы получить объект только что созданных экземпляров семейства необходимо дополнительно сделать финт ушами.

В теории, метод PromptForFamilyInstancePlacement мог бы возвратить список идентификаторов только что созданных объектов. Но так как метод ничего не возвращает, то придётся немного извертеться, чтобы добраться до созданных объектов. Можно перед тем как вызывать метод вставки экземпляра семейства, временно подписаться на событие DocumentChanged, которое возникает при изменении документа. И, после выполнения метода, сразу же отписаться от этого события. В обработчике события мы можем получить идентификаторы объектов, которые мы создали и нужно где-то их запомнить.

Я написал вот такой код:

Код - C#: [Выделить]

  /// <summary>
  /// Коллекция добавленных элементов
  /// </summary>
  List<ElementId> _added_element_ids
    = new List<ElementId>();
 
  void OnDocumentChanged(
    object sender,
    DocumentChangedEventArgs e )
  {
    _added_element_ids.AddRange(
      e.GetAddedElementIds() );
  }  

Ниже представлен полный исходный код команды, где видна подписка на событие.

Исходный код команды CmdTableLoadPlace

Ну, и на последок, предоставлю полный код команды CmdTableLoadPlace где видны все шаги, описанные выше.

Код - C#: [Выделить]

  /// <summary>
/// Загрузка семейства в проект, если оно еще не загружено
/// и размещение экземпляра этого семейства в проекте.
/// </summary>
[Transaction( TransactionMode.Manual )]
public class CmdTableLoadPlace : IExternalCommand
{
  /// <summary>
  ///Наименование семейства.
  /// </summary>
  public const string FamilyName = "family_api_table";
 
  /// <summary>
  /// Путь к папке с семействами.
  /// Вы можете воспользоваться методом
  /// Application.GetLibraryPaths
  /// для получения пути где размещаются файлы семейств.
  /// В данном случае для простоты возьмём файл семейства оттуда же где и исходники
  /// </summary>
  //const string _family_folder = "Z:/a/rvt";
  static string _family_folder
    = Path.GetDirectoryName(
      typeof( CmdTableLoadPlace )
        .Assembly.Location );
 
  /// <summary>
  /// Расширение файла семейств - RFA.
  /// </summary>
  const string _family_ext = "rfa";
 
  /// <summary>
  /// Путь к файлу семейства.
  /// </summary>
  static string _family_path = null;
 
  /// <summary>
  /// Возвращает полный путь к файлу семейства
  /// </summary>
  static string FamilyPath
  {
    get
    {
      if( null == _family_path )
      {
        _family_path = Path.Combine(
          _family_folder, FamilyName );
 
        _family_path = Path.ChangeExtension(
          _family_path, _family_ext );
      }
      return _family_path;
    }
  }
 
  /// <summary>
  /// Коллекция созданных объектов
  /// </summary>
  List<ElementId> _added_element_ids
    = new List<ElementId>();
 
  /// <summary>
  /// Главный метод внешней команды
  /// </summary>
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
 
    // Получаем семейство если оно уже загружено в проект
    Family family = Util.FindElementByName(
      doc, typeof( Family ), FamilyName ) as Family;
    if( null == family )
    {
      // если его еще нет в проекте
      // проверяем существует ли файл
 
      if( !File.Exists( FamilyPath ) )
      {
        Util.ErrorMsg( string.Format(
        "Проверьте наличие "
        + "файла семейства '{0}' в директории '{1}'.",
        FamilyName, _family_folder ) );
 
        return Result.Failed;
      }
 
      // Загрузка семейства из файла:
      using( Transaction tx = new Transaction( doc ) )
      {
        tx.Start( "Загрузка семейства" );
        doc.LoadFamily( FamilyPath, out family );
        tx.Commit();
      }
    }
 
    // Определяем типоразмер
    FamilySymbol symbol = null;
 
    foreach( FamilySymbol s in family.Symbols )
    {
      symbol = s;
 
    // Так как наше тестовое семейство содержит только один типоразмер
    // то возьмем первое и выйдем из цикла.
      break;
    }
 
    // Размещаем типоразмер:
    //Подписываемся на событие DocumentChanged
    // Для того чтобы получить идентификаторы элементов
    //  Созданных при помощи метода PromptForFamilyInstancePlacement :
    app.DocumentChanged
      += new EventHandler<DocumentChangedEventArgs>(
        OnDocumentChanged );
 
    _added_element_ids.Clear();
 
    // !Метод PromptForFamilyInstancePlacement нельзя  
  // использовать внутри транзакции
 
    uidoc.PromptForFamilyInstancePlacement( symbol );
 
    app.DocumentChanged
      -= new EventHandler<DocumentChangedEventArgs>(
        OnDocumentChanged );
 
    // Получаем доступ к созданным элементам:
 
    int n = _added_element_ids.Count();
 
    string msg = string.Format(
      "Размещено {0} экземпляров семейства {1} {2}{3}",
      n, family.Name,
      Util.PluralSuffix( n ),
      Util.DotOrColon( n ) );
 
    string ids = string.Join( ", ",
      _added_element_ids.Select<ElementId, string>(
        id => id.IntegerValue.ToString() ) );
 
    Util.InfoMsg2( msg, ids );
 
    return Result.Succeeded;
  }
 
  void OnDocumentChanged(
    object sender,
    DocumentChangedEventArgs e )
  {
    _added_element_ids.AddRange(
      e.GetAddedElementIds() );
  }
}
 