February 3, 2018 at 11:17Work with the KOMPAS-3D API → Lesson 6 → Saving a document in various formats
- Tutorial
We continue the series of articles on working with the KOMPAS-3D CAD API Sergey Norseev, software engineer at VNII Signal JSC, author of the book "Application Development for KOMPAS in Delphi." The environment used is C ++ Builder. In this lesson, we’ll talk about how to save documents.
To save a graphic document, the ksSaveDocument and ksSaveDocumentExEx methods of the ksDocument2D interface are used . Let's start with the first, its prototype is presented below.
The only parameter to the method is a string with the full name of the file into which you want to save the document. If the filename parameter contains an empty string, the document is saved along the path specified in the filename property of the ksDocumentParam interface (described briefly in the first part of the loop).
Note that if a file with the specified name already exists, then COMPAS will overwrite it.
If successful, the ksSaveDocument method returns true , and in case of an error, returns false .
The ksSaveDocumentEx method is similar to the ksSaveDocument method and, in fact, is an extended version of it. The following is a prototype methodksSaveDocumentEx .
As you can see from the prototype, in comparison with the ksSaveDocument method, the ksSaveDocumentEx method added one more parameter: an indication of which version of KOMPAS to save the document in. It has only three valid values:
-1 –– to the previous version;
0 - to the current version;
1 - to version 5.11.
An additional parameter is the only difference between the ksSaveDocumentEx method and the ksSaveDocument method . Calling the ksSaveDocumentEx method with a version parameter of zero is equivalent to calling the ksSaveDocument method .
According to Wikipedia: DXF (Drawing eXchange Format) is an open file format for exchanging graphical information between CAD applications. KOMPAS supports this format and allows us to save documents in this format.
To preserve the image document into DXF format using the method ksSaveToDXF interface ksDocument2D . Here is his prototype.
As the only parameter, it takes the full path to the file to which the document should be saved. If successful, the method returns true , and in case of error, false .
At its core, the DXF format is textual, and you can view the contents of the file in standard notepad. However, notepad does not fully support this format. To fully view the contents of the file, you can use the site sharecad.org, or a special program. The figure below shows a drawing saved in DXF format and open on sharecad.org.
DXF drawing open on sharecad.org
KOMPAS allows you to save documents in a raster format. To do this, you first need to fill in the ksRasterFormatParam parameters interface . Get this interface, you can use the method RasterFormatParam () interface ksDocument2D . This method has no input parameters and, if successful, returns the ksRasterFormatParam interface . In case of an error, it returns NULL . Consider the properties of the ksRasterFormatParam interface .
colorBPP - color of the bitmap image. Specifies the color depth of the image to be created. Valid values for this property are listed in the table below. Constants are declared in the ldefin2d.h module .
Valid values for the properties colorBPP
ColorType - the depth of color of the graphic image output. This property is similar to the colorBPP property and has the same valid values. The difference between the two is that the colorBPP property determines the color depth in the resulting file, and colorType determines the color depth when converting graphic objects into a raster form before they are saved to a file.
extResolution- Resolution of the bitmap in dots per inch. If the value of this property is zero, then the current screen resolution is used. The maximum resolution at which I was able to build the image was 960 dpi, although it is possible on more productive systems, you can build an image with even higher resolution.
extScale - scale. If the extScale value is greater than one, the image is magnified extScale times. If it is less than unity, then the image is reduced by 1 / extScale times.
format - the format of the bitmap image. Valid values for this property are shown in the table below. Constants are declared in the ldefin2d.h module .
Valid values for the format property
WMF format is not supported. According to KOMPAS documentation, when you try to save a document in this format, it will be saved in EMF format.
grayScale - a sign of the use of shades of gray. If the value of this property is true , then grayscale is used. If the property value is false , then the color image is saved.
multiPageOutput - flag to save document sheets in one file. If the value of this property is true , then all sheets of the document are saved in one file. If the value of this property is falsethen the sheets are saved in separate files. This property is used only for the TIFF format. But, as my experiments show, KOMPAS for the TIFF format saves the sheets of the document in one file, regardless of the value of the multiPageOutput property . For other formats, sheets are saved in separate files.
onlyThinLine - a sign of output in thin lines. If the value of this property is true , then the content of the document is displayed only in thin lines. If the value of this property is false , then the lines set for the objects are used in the document output.
pages - a list of output sheets of the document, presented as a string. List example: “ 1-18 , 24-25". In this example, sheets 1 through 18 are displayed, as well as 24 and 25 sheets. Sheet numbering is carried out from one. If the line is empty, then COMPASS does not use this property.
rangeindex - a sign of the choice of even and odd sheets. Valid property values:
0 - all sheets;
1 - odd sheets;
2 - even sheets.
The method at the ksRasterFormatParam interface is only one.
Init () - Resets all interface properties to zero. It has no input parameters and, if successful, returns true .
To save the document as a raster image, the SaveAsToRasterFormat method of the ksDocument2D interface is used . The following is its prototype.
The first parameter sets the full path to the file to which the document should be saved.
The second parameter contains the ksRasterFormatParam interface , which sets the saving options as a bitmap.
If successful, the SaveAsToRasterFormat method returns true , and in case of an error, false .
The following is an example of using this method.
In this example, a new document is created, which is saved as a jpeg image. Please note that since the document is empty, you will most likely see a blank sheet, and in non-commercial versions marked KOMPAS in the lower left corner, as in the figure below.
Marking a document in non-commercial versions (the edge of the sheet is shown conditionally)
As a result of saving the document, one file can be obtained, as well as several files. One file is obtained in the following cases:
In other cases, when you save the document, several files will be created. One file per sheet. At the same time, the number of the sheet stored in it is added to the file name. For example, if the parameter fileName method SaveAsToRasterFormat you specify the name of the file pict.jpeg, while maintaining the sheets with the numbers 1, 4, 5 will be created three files: pict (1) .jpeg, pict (4) .jpeg and pict (5) .jpeg.
If the file to which the sheets are saved already exists, then COMPAS behaves differently depending on how many files should be obtained. If 1 file, then it is overwritten without any warning. If several files are generated, then COMPASS displays the dialog box shown below. In this case, the SaveAsToRasterFormat methodwill not return control until the user closes the window.
Dialog box warning about overwriting a file.
These windows appear even if KOMPAS is launched in invisible mode.
The numbers of saved sheets are set using the pages and rangeindex properties . Consider how they are used by COMPASS.
If the pages property is not set or contains an empty string, and the value of the rangeindex property is zero , then all sheets of the document are saved. If the pages property is set, and the value of the rangeindex property is zero, then all sheets specified in the pages property are saved .
If the pages property contains an invalid sheet number, then it is ignored. For example, if for a document consisting of 5 sheets, the line “ 0,1,4,8 ” is set in the pages property , then sheets 1 and 4 will be saved. If pages contains the line “ invalid, 1, line, 3, ” then sheets 1 and 3 will be saved. If the rangeindex property is 1 ( 2 ) and the pages property is not set, then all the odd (even) sheets of the document will be saved. For example, if for a document consisting of 5 sheets, the rangeindex property is 1 , and the pages property is not set, then sheets: 1, 3, 5 will be saved.
If the rangeindex property is 1 ( 2 ) and the pages property is set , then the odd (even) sheets specified in the pages property will be saved . For example, provided
pages = " 1,2,3 ";
rangeindex = 1 ;
sheets 1 and 3 will be saved. Sheet 2 will not be saved exactly the same as sheet 5 if it is in the document.
Take a look at this example:
pages = " 1,3 ";
rangeindex = 2 .
In this case, not a single sheet will be saved. According to the value of the rangeindex propertyCOMPASS should save even sheets, but not even even sheets are specified in the pages property . Therefore, the SaveAsToRasterFormat method does not save anything and returns false .
To save the document as a raster image without compression, the SaveAsToUncompressedRasterFormat method of the ksDocument2D interface is used . This method is completely similar to the SaveAsToRasterFormat method discussed earlier. Therefore, I will not describe it.
Note that the difference between the SaveAsToRasterFormat and SaveAsToUncompressedRasterFormat methods appears only when working with TIFF files. For files of other types, they work exactly the same.
Conclusion
In this article, we looked at saving a graphic document in various formats. Remember that saving as a bitmap or DXF should in no way replace saving with the ksSaveDocument or ksSaveDocumentEx method .
In general, when developing an application for COMPASS, you should clearly determine who is responsible for saving the document: you, or the user. I believe that in most cases the user should be responsible for this. Your program creates a document and shows it to the user, who decides what to do next: save, or forget. However, if your program needs to change a large number of documents, then shifting the task of saving them to the user is ugly. In this case, the program must save the documents. Although it all depends on the task.
To be continued, follow the news of the blog.
Sergey Norseev, author of the book "Application Development for COMPAS in Delphi."
The content of the lesson series “Working with the COMPASS-3D API”
1. Basics
2. Drawing design
3. Correct connection to KOMPAS
4. Main label
5. Graphic primitives
6. Saving a document in various formats
7. Acquaintance with settings
8. More complex methods of writing to the main label
Easy save
To save a graphic document, the ksSaveDocument and ksSaveDocumentExEx methods of the ksDocument2D interface are used . Let's start with the first, its prototype is presented below.
BOOL ksSaveDocument (
BSTR fileName //полное имя файла
);
The only parameter to the method is a string with the full name of the file into which you want to save the document. If the filename parameter contains an empty string, the document is saved along the path specified in the filename property of the ksDocumentParam interface (described briefly in the first part of the loop).
Note that if a file with the specified name already exists, then COMPAS will overwrite it.
If successful, the ksSaveDocument method returns true , and in case of an error, returns false .
The ksSaveDocumentEx method is similar to the ksSaveDocument method and, in fact, is an extended version of it. The following is a prototype methodksSaveDocumentEx .
BOOL ksSaveDocumentEx (
BSTR fileName, //полное имя файла
long version //для какой версии КОМПАС сохранять
);
As you can see from the prototype, in comparison with the ksSaveDocument method, the ksSaveDocumentEx method added one more parameter: an indication of which version of KOMPAS to save the document in. It has only three valid values:
-1 –– to the previous version;
0 - to the current version;
1 - to version 5.11.
An additional parameter is the only difference between the ksSaveDocumentEx method and the ksSaveDocument method . Calling the ksSaveDocumentEx method with a version parameter of zero is equivalent to calling the ksSaveDocument method .
Save to DXF format
According to Wikipedia: DXF (Drawing eXchange Format) is an open file format for exchanging graphical information between CAD applications. KOMPAS supports this format and allows us to save documents in this format.
To preserve the image document into DXF format using the method ksSaveToDXF interface ksDocument2D . Here is his prototype.
BOOL ksSaveToDXF (
LPCTSTR dxfFileName //полное имя файла
);
As the only parameter, it takes the full path to the file to which the document should be saved. If successful, the method returns true , and in case of error, false .
At its core, the DXF format is textual, and you can view the contents of the file in standard notepad. However, notepad does not fully support this format. To fully view the contents of the file, you can use the site sharecad.org, or a special program. The figure below shows a drawing saved in DXF format and open on sharecad.org.
DXF drawing open on sharecad.org
Raster format save options
KOMPAS allows you to save documents in a raster format. To do this, you first need to fill in the ksRasterFormatParam parameters interface . Get this interface, you can use the method RasterFormatParam () interface ksDocument2D . This method has no input parameters and, if successful, returns the ksRasterFormatParam interface . In case of an error, it returns NULL . Consider the properties of the ksRasterFormatParam interface .
colorBPP - color of the bitmap image. Specifies the color depth of the image to be created. Valid values for this property are listed in the table below. Constants are declared in the ldefin2d.h module .
Valid values for the properties colorBPP
ColorType - the depth of color of the graphic image output. This property is similar to the colorBPP property and has the same valid values. The difference between the two is that the colorBPP property determines the color depth in the resulting file, and colorType determines the color depth when converting graphic objects into a raster form before they are saved to a file.
extResolution- Resolution of the bitmap in dots per inch. If the value of this property is zero, then the current screen resolution is used. The maximum resolution at which I was able to build the image was 960 dpi, although it is possible on more productive systems, you can build an image with even higher resolution.
extScale - scale. If the extScale value is greater than one, the image is magnified extScale times. If it is less than unity, then the image is reduced by 1 / extScale times.
format - the format of the bitmap image. Valid values for this property are shown in the table below. Constants are declared in the ldefin2d.h module .
Valid values for the format property
WMF format is not supported. According to KOMPAS documentation, when you try to save a document in this format, it will be saved in EMF format.
grayScale - a sign of the use of shades of gray. If the value of this property is true , then grayscale is used. If the property value is false , then the color image is saved.
multiPageOutput - flag to save document sheets in one file. If the value of this property is true , then all sheets of the document are saved in one file. If the value of this property is falsethen the sheets are saved in separate files. This property is used only for the TIFF format. But, as my experiments show, KOMPAS for the TIFF format saves the sheets of the document in one file, regardless of the value of the multiPageOutput property . For other formats, sheets are saved in separate files.
onlyThinLine - a sign of output in thin lines. If the value of this property is true , then the content of the document is displayed only in thin lines. If the value of this property is false , then the lines set for the objects are used in the document output.
pages - a list of output sheets of the document, presented as a string. List example: “ 1-18 , 24-25". In this example, sheets 1 through 18 are displayed, as well as 24 and 25 sheets. Sheet numbering is carried out from one. If the line is empty, then COMPASS does not use this property.
rangeindex - a sign of the choice of even and odd sheets. Valid property values:
0 - all sheets;
1 - odd sheets;
2 - even sheets.
The method at the ksRasterFormatParam interface is only one.
Init () - Resets all interface properties to zero. It has no input parameters and, if successful, returns true .
Saving as a bitmap
To save the document as a raster image, the SaveAsToRasterFormat method of the ksDocument2D interface is used . The following is its prototype.
BOOL SaveAsToRasterFormat (
BSTR fileName, //Полный путь к файлу
LPDISPATCH rasterPar //Параметры сохранения
);
The first parameter sets the full path to the file to which the document should be saved.
The second parameter contains the ksRasterFormatParam interface , which sets the saving options as a bitmap.
If successful, the SaveAsToRasterFormat method returns true , and in case of an error, false .
The following is an example of using this method.
//Формируем путь к файлу, в который будем сохранять
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();
In this example, a new document is created, which is saved as a jpeg image. Please note that since the document is empty, you will most likely see a blank sheet, and in non-commercial versions marked KOMPAS in the lower left corner, as in the figure below.
Marking a document in non-commercial versions (the edge of the sheet is shown conditionally)
Saving multi-sheet documents
As a result of saving the document, one file can be obtained, as well as several files. One file is obtained in the following cases:
- the saved document consists of one sheet;
- only 1 sheet of the document is saved;
- The document is saved in TIFF format.
In other cases, when you save the document, several files will be created. One file per sheet. At the same time, the number of the sheet stored in it is added to the file name. For example, if the parameter fileName method SaveAsToRasterFormat you specify the name of the file pict.jpeg, while maintaining the sheets with the numbers 1, 4, 5 will be created three files: pict (1) .jpeg, pict (4) .jpeg and pict (5) .jpeg.
If the file to which the sheets are saved already exists, then COMPAS behaves differently depending on how many files should be obtained. If 1 file, then it is overwritten without any warning. If several files are generated, then COMPASS displays the dialog box shown below. In this case, the SaveAsToRasterFormat methodwill not return control until the user closes the window.
Dialog box warning about overwriting a file.
These windows appear even if KOMPAS is launched in invisible mode.
The numbers of saved sheets are set using the pages and rangeindex properties . Consider how they are used by COMPASS.
If the pages property is not set or contains an empty string, and the value of the rangeindex property is zero , then all sheets of the document are saved. If the pages property is set, and the value of the rangeindex property is zero, then all sheets specified in the pages property are saved .
If the pages property contains an invalid sheet number, then it is ignored. For example, if for a document consisting of 5 sheets, the line “ 0,1,4,8 ” is set in the pages property , then sheets 1 and 4 will be saved. If pages contains the line “ invalid, 1, line, 3, ” then sheets 1 and 3 will be saved. If the rangeindex property is 1 ( 2 ) and the pages property is not set, then all the odd (even) sheets of the document will be saved. For example, if for a document consisting of 5 sheets, the rangeindex property is 1 , and the pages property is not set, then sheets: 1, 3, 5 will be saved.
If the rangeindex property is 1 ( 2 ) and the pages property is set , then the odd (even) sheets specified in the pages property will be saved . For example, provided
pages = " 1,2,3 ";
rangeindex = 1 ;
sheets 1 and 3 will be saved. Sheet 2 will not be saved exactly the same as sheet 5 if it is in the document.
Take a look at this example:
pages = " 1,3 ";
rangeindex = 2 .
In this case, not a single sheet will be saved. According to the value of the rangeindex propertyCOMPASS should save even sheets, but not even even sheets are specified in the pages property . Therefore, the SaveAsToRasterFormat method does not save anything and returns false .
Saving without compression
To save the document as a raster image without compression, the SaveAsToUncompressedRasterFormat method of the ksDocument2D interface is used . This method is completely similar to the SaveAsToRasterFormat method discussed earlier. Therefore, I will not describe it.
Note that the difference between the SaveAsToRasterFormat and SaveAsToUncompressedRasterFormat methods appears only when working with TIFF files. For files of other types, they work exactly the same.
Conclusion
In this article, we looked at saving a graphic document in various formats. Remember that saving as a bitmap or DXF should in no way replace saving with the ksSaveDocument or ksSaveDocumentEx method .
In general, when developing an application for COMPASS, you should clearly determine who is responsible for saving the document: you, or the user. I believe that in most cases the user should be responsible for this. Your program creates a document and shows it to the user, who decides what to do next: save, or forget. However, if your program needs to change a large number of documents, then shifting the task of saving them to the user is ugly. In this case, the program must save the documents. Although it all depends on the task.
To be continued, follow the news of the blog.
Sergey Norseev, author of the book "Application Development for COMPAS in Delphi."