Using the KOMPAS-3D API → Lesson 6 → Saving a document in various formats
We continue the cycle of articles on working with the CAD API KOMPAS-3D Sergey Norseev, an engineer-programmer of the All-Russian Scientific-Research Institute “Signal”, the author of the book “Development of applications for KOMPAS in Delphi”. C ++ Builder is used as the medium. In this lesson we will talk about how to save documents.
To save a graphic document, the ksSaveDocument and ksSaveDocumentEx methods of the ksDocument2D interface are used . Let's start with the first, its prototype is presented below.
')
The only parameter of the method is a string with the full name of the file in which you want to save the document. If the filename parameter contains an empty string, then the document is saved along the path specified in the filename property of the ksDocumentParam interface (briefly described in the first part of the cycle).
Note that if a file with the specified name already exists, KOMPAS will overwrite it.
If successful, the ksSaveDocument method returns true , and in case of error, false .
The ksSaveDocumentEx method is similar to the ksSaveDocument method and, in fact, is its extended version. The following is a prototype of the ksSaveDocumentEx method.
As can be seen from the prototype, in comparison with the ksSaveDocument method in the ksSaveDocumentEx method, one more parameter was added: a sign in which version of KOMPAS to save the document. It has only three valid values:
-1 –in previous version;
0 - to the current version;
1 - in version 5.11.
The additional parameter is the only difference between the ksSaveDocumentEx method and the ksSaveDocument method. Calling the ksSaveDocumentEx method with the version parameter equal to zero is equivalent to calling the ksSaveDocument method.
According to Wikipedia: DXF (Drawing eXchange Format) is an open file format for exchanging graphic information between CAD applications. KOMPAS supports this format and allows us to save documents in this format.
To save the graphic document in the DXF format, use the ksSaveToDXF method of the ksDocument2D interface. Here is its prototype.
As the only parameter, it takes the full path to the file in which to save the document. If successful, the method returns true , and in case of error, false .
At its core, the DXF format is text-based, and you can view the contents of the file in a standard notepad. However, the notebook does not fully support this format. To view the full content of the file, you can use the sharecad.org site, or a special program. The figure below shows a drawing saved in DXF format and opened on the sharecad.org portal.
DXF drawing open on the sharecad.org portal
KOMPAS allows you to save documents in raster format. To do this, you first need to fill in the ksRasterFormatParam parameter interface . You can get this interface using the ksDocument2D interface RasterFormatParam () method . This method has no input parameters and, if successful, returns the ksRasterFormatParam interface. If an error occurs, it returns a NULL value. Consider the properties of the ksRasterFormatParam interface.
colorBPP - bitmap color. Sets the color depth of the image being created. Valid values for this property are listed in the table below. Constants are declared in the ldefin2d.h module.
Valid values for the colorBPP property
colorType - the color depth of the output graphic image. This property is similar to the colorBPP property and has the same valid values. The difference between them is that the colorBPP property determines the color depth in the final file, and colorType determines the color depth when converting graphic objects to raster form before saving them 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 managed to build an image was 960 dpi, although it is possible to build an image with even higher resolution on more productive systems.
extScale - scale. If extScale value is greater than one, then the image is increased in extScale times. If it is less than one, then the image is reduced by 1 / extScale times.
format - raster image format. 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 the KOMPAS documentation, when you try to save a document in this format, it will be saved in EMF format.
greyScale is a sign of the use of shades of gray. If the value of this property is true , then shades of gray are used. If the value of the property is false , then a color image is saved.
multiPageOutput - sign of saving sheets of the document in a single 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 false , then the sheets are saved in separate files. This property is used only for TIFF format. But, as shown by my experiments, KOMPAS for the TIFF format saves the sheets of a document into one file, regardless of the value of the multiPageOutput property. For other formats, the sheets are saved in separate files.
onlyThinLine is 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 output of the document uses the lines set for the objects.
pages - the list of output sheets of the document, presented as a string. Example list: " 1-18 , 24-25 ." In this example, sheets 1 through 18 are displayed, as well as 24 and 25 sheets. Sheets are numbered from one. If the string is empty, KOMPAS 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.
There is only one method for the ksRasterFormatParam interface.
Init () - resets the values of all interface properties. It has no input parameters and, if successful, returns true .
To save the document as a bitmap image, use the Save AsToRasterFormat method of the ksDocument2D interface. Below is its prototype.
The first parameter specifies the full path to the file in which to save the document.
The second parameter contains the ksRasterFormatParam interface, which specifies the save parameters as a bitmap image.
On success, the SaveAsToRasterFormat method returns true , and on 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.
Document mark in non-commercial versions (the edge of the sheet is shown conditionally)
As a result, saving a document can result in one file or 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. In this case, the number of the sheet stored in it is added to the file name. For example, if you specify the name of the pict.jpeg file in the fileName parameter of the SaveAsToRasterFormat method, then saving the sheets with numbers 1, 4, 5 will create three files: pict (1) .jpeg, pict (4) .jpeg and pict (5) .jpeg.
If the file in which the sheets are saved already exists, then KOMPAS behaves differently depending on how many files it should turn out. If 1 file, then it is overwritten without any warning. If multiple files are being generated, KOMPAS displays the dialog box shown below. In this case, the SaveAsToRasterFormat method will not return until the user closes the window.
Dialog box warning about file rewriting
These windows appear even if KOMPAS is running in invisible mode.
The numbers of stored sheets are set using the properties pages and rangeindex . Consider how they are used KOMPAS.
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 incorrect sheet number, then it is ignored. For example, if for a document consisting of 5 sheets, the pages property is set to “ 0,1,4,8 ”, then pages 1 and 4 will be saved. If pages contains the string “ invalid, 1, line, 3, ” Sheets 1 and 3 will be saved.
If the rangeindex property is 1 ( 2 ), and the pages property is not set, then all 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 the sheets will be saved: 1, 3, 5.
If the rangeindex property is 1 ( 2 ) and the pages property is set, then 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 property , KOMPAS should save even sheets, but not even a single sheet is specified in the pages property. Therefore, the SaveAsToRasterFormat method does not save anything and returns false .
To save the document as a non-compressed bitmap image, use the Save AsToUncompressedRasterFormat method of the ksDocument2D interface. This method is completely analogous to the SaveAsToRasterFormat method discussed earlier. Therefore, I will not describe it.
Note that the difference between the SaveAsToRasterFormat and SaveAsToUncompressedRasterFormat methods is manifested only when working with TIFF files. For other file types, they work exactly the same.
Conclusion
In this article, we looked at saving a graphic document in various formats. Do not forget that saving as a bitmap or DXF should in no case replace the saving using the ksSaveDocument or ksSaveDocumentEx method .
In general, when developing an application for KOMPAS, you should clearly define who is responsible for saving the document: you, or the user. I believe that in most cases the user must be responsible for this. Your program creates a document and shows it to the user, who decides what to do with it further: save, or forget. However, if your program has to change a large number of documents, then it is ugly to shift the task of saving them to the user. In this case, the program must save the documents. Although it all depends on the task.
To be continued, stay tuned to the blog.
Sergey Norseev, author of the book “Development of applications for KOMPAS in Delphi”.
Content of the cycle of lessons “Working with the API KOMPAS-3D”
1. Basics
2. Design drawing
3. Correct connection to COMPAS
4. Title Block
5. Graphic primitives
6. Saving a document in various formats
7. Getting to know the settings
8. More complex methods of writing to the main title
Simple save
To save a graphic document, the ksSaveDocument and ksSaveDocumentEx 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 of the method is a string with the full name of the file in which you want to save the document. If the filename parameter contains an empty string, then the document is saved along the path specified in the filename property of the ksDocumentParam interface (briefly described in the first part of the cycle).
Note that if a file with the specified name already exists, KOMPAS will overwrite it.
If successful, the ksSaveDocument method returns true , and in case of error, false .
The ksSaveDocumentEx method is similar to the ksSaveDocument method and, in fact, is its extended version. The following is a prototype of the ksSaveDocumentEx method.
BOOL ksSaveDocumentEx ( BSTR fileName, // long version // ); As can be seen from the prototype, in comparison with the ksSaveDocument method in the ksSaveDocumentEx method, one more parameter was added: a sign in which version of KOMPAS to save the document. It has only three valid values:
-1 –in previous version;
0 - to the current version;
1 - in version 5.11.
The additional parameter is the only difference between the ksSaveDocumentEx method and the ksSaveDocument method. Calling the ksSaveDocumentEx method with the version parameter equal to 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 graphic information between CAD applications. KOMPAS supports this format and allows us to save documents in this format.
To save the graphic document in the DXF format, use the ksSaveToDXF method of the ksDocument2D interface. Here is its prototype.
BOOL ksSaveToDXF ( LPCTSTR dxfFileName // ); As the only parameter, it takes the full path to the file in which to save the document. If successful, the method returns true , and in case of error, false .
At its core, the DXF format is text-based, and you can view the contents of the file in a standard notepad. However, the notebook does not fully support this format. To view the full content of the file, you can use the sharecad.org site, or a special program. The figure below shows a drawing saved in DXF format and opened on the sharecad.org portal.
DXF drawing open on the sharecad.org portal
Raster save options
KOMPAS allows you to save documents in raster format. To do this, you first need to fill in the ksRasterFormatParam parameter interface . You can get this interface using the ksDocument2D interface RasterFormatParam () method . This method has no input parameters and, if successful, returns the ksRasterFormatParam interface. If an error occurs, it returns a NULL value. Consider the properties of the ksRasterFormatParam interface.
colorBPP - bitmap color. Sets the color depth of the image being created. Valid values for this property are listed in the table below. Constants are declared in the ldefin2d.h module.
Valid values for the colorBPP property
colorType - the color depth of the output graphic image. This property is similar to the colorBPP property and has the same valid values. The difference between them is that the colorBPP property determines the color depth in the final file, and colorType determines the color depth when converting graphic objects to raster form before saving them 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 managed to build an image was 960 dpi, although it is possible to build an image with even higher resolution on more productive systems.
extScale - scale. If extScale value is greater than one, then the image is increased in extScale times. If it is less than one, then the image is reduced by 1 / extScale times.
format - raster image format. 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 the KOMPAS documentation, when you try to save a document in this format, it will be saved in EMF format.
greyScale is a sign of the use of shades of gray. If the value of this property is true , then shades of gray are used. If the value of the property is false , then a color image is saved.
multiPageOutput - sign of saving sheets of the document in a single 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 false , then the sheets are saved in separate files. This property is used only for TIFF format. But, as shown by my experiments, KOMPAS for the TIFF format saves the sheets of a document into one file, regardless of the value of the multiPageOutput property. For other formats, the sheets are saved in separate files.
onlyThinLine is 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 output of the document uses the lines set for the objects.
pages - the list of output sheets of the document, presented as a string. Example list: " 1-18 , 24-25 ." In this example, sheets 1 through 18 are displayed, as well as 24 and 25 sheets. Sheets are numbered from one. If the string is empty, KOMPAS 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.
There is only one method for the ksRasterFormatParam interface.
Init () - resets the values of all interface properties. It has no input parameters and, if successful, returns true .
Saving as a raster image
To save the document as a bitmap image, use the Save AsToRasterFormat method of the ksDocument2D interface. Below is its prototype.
BOOL SaveAsToRasterFormat ( BSTR fileName, // LPDISPATCH rasterPar // ); The first parameter specifies the full path to the file in which to save the document.
The second parameter contains the ksRasterFormatParam interface, which specifies the save parameters as a bitmap image.
On success, the SaveAsToRasterFormat method returns true , and on 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.
Document mark in non-commercial versions (the edge of the sheet is shown conditionally)
Saving multi-sheet documents
As a result, saving a document can result in one file or 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. In this case, the number of the sheet stored in it is added to the file name. For example, if you specify the name of the pict.jpeg file in the fileName parameter of the SaveAsToRasterFormat method, then saving the sheets with numbers 1, 4, 5 will create three files: pict (1) .jpeg, pict (4) .jpeg and pict (5) .jpeg.
If the file in which the sheets are saved already exists, then KOMPAS behaves differently depending on how many files it should turn out. If 1 file, then it is overwritten without any warning. If multiple files are being generated, KOMPAS displays the dialog box shown below. In this case, the SaveAsToRasterFormat method will not return until the user closes the window.
Dialog box warning about file rewriting
These windows appear even if KOMPAS is running in invisible mode.
The numbers of stored sheets are set using the properties pages and rangeindex . Consider how they are used KOMPAS.
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 incorrect sheet number, then it is ignored. For example, if for a document consisting of 5 sheets, the pages property is set to “ 0,1,4,8 ”, then pages 1 and 4 will be saved. If pages contains the string “ invalid, 1, line, 3, ” Sheets 1 and 3 will be saved.
If the rangeindex property is 1 ( 2 ), and the pages property is not set, then all 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 the sheets will be saved: 1, 3, 5.
If the rangeindex property is 1 ( 2 ) and the pages property is set, then 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 property , KOMPAS should save even sheets, but not even a single sheet is specified in the pages property. Therefore, the SaveAsToRasterFormat method does not save anything and returns false .
Save without compression
To save the document as a non-compressed bitmap image, use the Save AsToUncompressedRasterFormat method of the ksDocument2D interface. This method is completely analogous to the SaveAsToRasterFormat method discussed earlier. Therefore, I will not describe it.
Note that the difference between the SaveAsToRasterFormat and SaveAsToUncompressedRasterFormat methods is manifested only when working with TIFF files. For other file types, they work exactly the same.
Conclusion
In this article, we looked at saving a graphic document in various formats. Do not forget that saving as a bitmap or DXF should in no case replace the saving using the ksSaveDocument or ksSaveDocumentEx method .
In general, when developing an application for KOMPAS, you should clearly define who is responsible for saving the document: you, or the user. I believe that in most cases the user must be responsible for this. Your program creates a document and shows it to the user, who decides what to do with it further: save, or forget. However, if your program has to change a large number of documents, then it is ugly to shift the task of saving them to the user. In this case, the program must save the documents. Although it all depends on the task.
To be continued, stay tuned to the blog.
Sergey Norseev, author of the book “Development of applications for KOMPAS in Delphi”.Source: https://habr.com/ru/post/346772/
All Articles