Работа с API КОМПАС-3D → Урок 6 → Сохранение документа в различные форматы03.02.2018 18:03

Продолжаем цикл статей по работе с API САПР КОМПАС-3D Сергея Норсеева, инженера-программиста АО «ВНИИ «Сигнал», автора книги «Разработка приложений под КОМПАС в Delphi». В качестве среды используется C++ Builder. В этом уроке поговорим о том, как сохранять документы.

hwo8xljzsc7a73fs-vhgjzczzhk.png

Содержание цикла уроков «Работа с API КОМПАС-3D»


1. Основы
2. Оформление чертежа
3. Корректное подключение к КОМПАС
4. Основная надпись
5. Графические примитивы
6. Сохранение документа в различные форматы
7. Знакомство с настройками


Простое сохранение


Для сохранения графического документа используются методы ksSaveDocument и ksSaveDocumentEx интерфейса ksDocument2D. Начнем с первого, его прототип представлен ниже.

BOOL ksSaveDocument (
BSTR fileName	//полное имя файла
);


Единственный параметр метода — строка с полным именем файла, в который нужно сохранить документ. Если параметр filename содержит пустую строку, то документ сохраняется по пути заданному в свойстве filename интерфейса ksDocumentParam (кратко описывался в первой части цикла).

Учтите, что если файл с указанным именем уже существует, то КОМПАС перезапишет его.
В случае успеха метод ksSaveDocument возвращает значение true, а в случае ошибки — значение false.

Метод ksSaveDocumentEx похож на метод ksSaveDocument и, по сути, является его расширенной версией. Ниже приводится прототип метода ksSaveDocumentEx.

BOOL ksSaveDocumentEx (
BSTR fileName,	//полное имя файла
long version	//для какой версии КОМПАС сохранять
);


Как видно из прототипа по сравнению с методом ksSaveDocument в методе ksSaveDocumentEx добавился еще один параметр: признак того, в какой версии КОМПАС сохранять документ. У него всего три допустимых значения:

-1 –в предыдущую версию;
0 — в текущую версию;
1 — в версию 5.11.

Дополнительный параметр — единственное отличие метода ksSaveDocumentEx от метода ksSaveDocument. Вызов метода ksSaveDocumentEx с параметром version равным нулю, эквивалентен вызову метода ksSaveDocument.

Сохранение в формат DXF


Согласно Википедии: DXF (Drawing eXchange Format) — отрытый формат файлов для обмена графической информацией между приложениями САПР. КОМПАС поддерживает этот формат и позволяет нам сохранять документы в этом формате.
Для сохранения графического документа в формат DXF используется метод ksSaveToDXF интерфейса ksDocument2D. Вот его прототип.

BOOL ksSaveToDXF (
LPCTSTR dxfFileName	//полное имя файла
);


В качестве единственного параметра он принимает полный путь к файлу, в который нужно сохранить документ. В случае успеха метод возвращает значение true, а в случае ошибки — значение false.

По своей сути формат DXF является текстовым, и содержимое файла вы можете просмотреть в стандартном блокноте. Однако блокнот не поддерживает этот формат полностью. Для полноценного просмотра содержимого файла можно воспользоваться сайтом sharecad.org, или специальной программой. На рисунке ниже показан чертеж, сохраненный в формате DXF и открытый на портале sharecad.org.

b_plfhoykbavckukfekfvalc54o.png
Чертеж в формате DXF открытый на портале sharecad.org

Параметры сохранения в растровом формате


КОМПАС позволяет сохранять документы в растровом формате. Для этого вначале нужно заполнить интерфейс параметров ksRasterFormatParam. Получить данный интерфейс можно с помощью метода RasterFormatParam () интерфейса ksDocument2D. Данный метод не имеет входных параметров и в случае успеха возвращает интерфейс ksRasterFormatParam. В случае ошибки он возвращает значение NULL. Рассмотрим свойства интерфейса ksRasterFormatParam.

colorBPP — цветность растрового изображения. Задает глубину цвета создаваемого изображения. Допустимые значения данного свойства перечислены в таблице ниже. Константы объявлены в модуле ldefin2d.h.

gz7n4zn32stev9l5gelp4jrbv8i.png
Допустимые значения свойства colorBPP

colorType — глубина цвета вывода графического изображения. Данное свойство похоже на свойство colorBPP и имеет те же допустимые значения. Разница между ними в том, что свойство colorBPP определяет глубину цвета в итоговом файле, а colorType — глубину цвета при преобразовании графических объектов в растровую форму до их сохранения в файл.
extResolution — разрешение растрового изображения в точках на дюйм. Если значение этого свойства равно нулю, то используется текущее разрешение экрана. Максимальное разрешение, при котором мне удалось построить изображение, составило 960 точек на дюйм, хотя возможно на более производительных системах можно построить изображение и с еще большим разрешением.
extScale — масштаб. Если значение extScale больше единицы, то изображение увеличивается в extScale раз. Если же оно меньше единицы, то изображение уменьшается в 1/extScale раз.
format — формат растрового изображения. Допустимые значения этого свойства приведены в таблице ниже. Константы объявлены в модуле ldefin2d.h.

kwlya0iflugutjgzaqst7vjezac.png
Допустимые значения свойства format

Формат WMF не поддерживается. Согласно документации КОМПАС при попытке сохранить документ в этом формате, он будет сохранен в формате EMF.

greyScale — признак использования оттенков серого. Если значение данного свойства равно true, то используются оттенки серого. Если же значение свойства равно false, то сохраняется цветное изображение.
multiPageOutput — признак сохранения листов документа в одном файле. Если значение данного свойства равно true, то все листы документа сохраняются в одном файле. Если же значение этого свойства равно false, то листы сохраняются в отдельных файлах. Данное свойство используется только для формата TIFF. Но, как показывают мои эксперименты, КОМПАС для формата TIFF сохраняет листы документа в один файл вне зависимости от значения свойства multiPageOutput. Для других форматов листы сохраняются в отдельные файлы.
onlyThinLine — признак вывода в тонких линиях. Если значение этого свойства равно true, то содержимое документа выводится только в тонких линиях. Если же значение этого свойства равно false, то при выводе документа используются линии, установленные для объектов.
pages — список выводимых листов документа, представленный в виде строки. Пример списка:»1–18, 24–25». В данном примере выводятся листы с 1 по 18, а так же 24 и 25 листы. Нумерация листов ведется с единицы. Если строка пустая, то КОМПАС не использует данное свойство.
rangeindex — признак выбора четных и нечетных листов. Допустимые значения свойства:
0 — все листы;
1 — нечетные листы;
2 — четные листы.
Метод у интерфейса ksRasterFormatParam всего один.
Init () — обнуляет значения всех свойств интерфейса. Он не имеет входных параметров и, в случае успеха возвращает значение true.

Сохранение в виде растрового изображения


Для сохранения документа в виде растрового изображения используется метод SaveAsToRasterFormat интерфейса ksDocument2D. Ниже приводится его прототип.

BOOL SaveAsToRasterFormat (
BSTR fileName,		//Полный путь к файлу
LPDISPATCH rasterPar	//Параметры сохранения
);


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

В случае успеха метод SaveAsToRasterFormat возвращает значение true, а в случае ошибки — false.

Ниже приводится пример использования данного метода.

//Формируем путь к файлу, в который будем сохранять
WideString str_filepath;
str_filepath = ExtractFileDir(Application->ExeName);
str_filepath += L"\\MyNewDocument.jpg";

//Подключаемся к КОМПАС
KompasObjectPtr kompas;
kompas.CreateInstance(L"KOMPAS.Application.5");

//Подготавливаем параметры документа
DocumentParamPtr DocumentParam;
DocumentParam=(DocumentParamPtr)kompas->GetParamStruct(ko_DocumentParam);
DocumentParam->Init();
DocumentParam->type= lt_DocSheetStandart;//Чертеж на стандартном листе

//Создаем документ
Document2DPtr Document2D;
Document2D = (Document2DPtr)kompas->Document2D();
Document2D->ksCreateDocument(DocumentParam);

//Подготавливаем параметры сохранения в растр
RasterFormatParamPtr RasterFormatParam;
RasterFormatParam = (RasterFormatParamPtr)Document2D->RasterFormatParam();
RasterFormatParam->Init();
RasterFormatParam->set_colorBPP(BPP_COLOR_24);
RasterFormatParam->set_colorType(BPP_COLOR_24);
RasterFormatParam->set_extResolution(0);
RasterFormatParam->set_extScale(1.0);
RasterFormatParam->set_format(FORMAT_JPG);
RasterFormatParam->set_greyScale(false);
RasterFormatParam->set_onlyThinLine(false);
RasterFormatParam->set_pages(SysAllocString(L""));
RasterFormatParam->set_rangeIndex(0);

//Сохраняем в виде растрового изображения
Document2D->SaveAsToRasterFormat(SysAllocString(str_filepath.c_bstr()), RasterFormatParam);

//Освобождаем ресурсы
RasterFormatParam.Unbind();
Document2D.Unbind();

kompas->set_Visible(true);
kompas.Unbind();


В данном примере создается новый документ, который сохраняется в виде jpeg изображения. Учтите, поскольку документ пустой вы, скорее всего, увидите пустой лист, а в некоммерческих версиях с пометкой КОМПАС в левом нижнем углу, как на рисунке ниже.

dbka0d1_wghorkki5n2o29imfxg.png
Пометка документа в некоммерческих версиях (край листа показан условно)

Сохранение многолистовых документов


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

  • сохраняемый документ состоит из одного листа;
  • сохраняется только 1 лист документа;
  • документ сохраняется в формате TIFF.


В остальных случаях при сохранении документа будет создано несколько файлов. По одному файлу на каждый лист. При этом к наименованию файла добавляется номер сохраняемого в нём листа. Например, если в параметре fileName метода SaveAsToRasterFormat вы указали наименование файла pict.jpeg, то при сохранении листов с номерами 1, 4, 5 будет создано три файла: pict (1).jpeg, pict (4).jpeg и pict (5).jpeg.

Если файл, в который сохраняются листы, уже существует, то КОМПАС ведет себя по-разному в зависимости от того, сколько файлов должно получиться. Если 1 файл, то он перезаписывается без какого-либо предупреждения. Если же образуется несколько файлов, то КОМПАС выдает диалоговое окно, показанное ниже. При этом метод SaveAsToRasterFormat не вернет управление до тех пор, пока пользователь не закроет окно.

ro2vg29jq0er4vcwmoinpxmf4yo.png
Диалоговое окно, предупреждающее о перезаписи файла

Данные окна появляются даже в том случае, если КОМПАС запущен в невидимом режиме.

Номера сохраняемых листов задаются с помощью свойств pages и rangeindex. Рассмотрим, как они используются КОМПАС.

Если свойство pages не задано или содержит пустую строку, а значение свойства rangeindex равно нулю, то сохраняются все листы документа. Если свойство pages задано, а значение свойства rangeindex равно нулю, то сохраняются все листы, указанные в свойстве pages.

Если свойство pages содержит некорректный номер листа, то он игнорируется. Например, если для документа, состоящего из 5 листов, в свойстве pages задать строку »0,1,4,8», то будут сохранены листы 1 и 4. Если pages содержит строку »неверная,1, строка,3, », то будут сохранены листы 1 и 3.

Если свойство rangeindex равно 1 (2), а свойство pages не задано, то будут сохранены все нечетные (четные) листы документа. Например, если для документа, состоящего из 5 листов, свойство rangeindex равно 1, а свойство pages не задано, то будут сохранены листы: 1, 3, 5.

Если свойство rangeindex равно 1 (2) и задано свойство pages, то будут сохранены нечетные (четные) листы, указанные в свойстве pages. Например, при условии
pages = »1,2,3»;
rangeindex = 1;
будут сохранены листы 1 и 3. Лист 2 сохраняться не будет точно так, же как и лист 5, если он есть в документе.
Взглянем на такой пример:
pages = »1,3»;
rangeindex = 2.
В этом случае не будет сохранено ни одного листа. Согласно значению свойства rangeindex КОМПАС должен сохранить четные листы, но в свойстве pages не указано ни одного четного листа. Поэтому метод SaveAsToRasterFormat ничего не сохраняет и возвращает значение false.

Сохранение без сжатия


Для сохранения документа в виде растрового изображения без сжатия используется метод SaveAsToUncompressedRasterFormat интерфейса ksDocument2D. Данный метод полностью аналогичен методу SaveAsToRasterFormat, рассмотренному ранее. Поэтому описывать его я не буду.

Учтите, что различие между методами SaveAsToRasterFormat и SaveAsToUncompressedRasterFormat проявляется только при работе с файлами формата TIFF. Для файлов других типов они работают абсолютно одинаково.

Заключение
В данной статье мы рассмотрели сохранение графического документа в различные форматы. Не забывайте, что сохранение в виде растрового изображения или DXF ни в коем случае не должно заменять сохранения с помощью метода ksSaveDocument или ksSaveDocumentEx.

Вообще при разработке приложения под КОМПАС вы должны четко определиться с тем, кто отвечает за сохранение документа: вы, или пользователь. Я считаю, что в большинстве случаев за это должен отвечать пользователь. Ваша программа создает документ и показывает его пользователю, который и решает, что с ним делать дальше: сохранить, или забыть. Однако, если ваша программа должна изменить большое количество документов, то перекладывать задачу их сохранения на пользователя некрасиво. В этом случае сохранять документы должна программа. Хотя всё зависит от поставленной задачи.

Продолжение следует, следите за новостями блога.

595eeef271b24830b3578751fcb52716.png Сергей Норсеев, автор книги «Разработка приложений под КОМПАС в Delphi».

© Habrahabr.ru