The PDF export process can be managed with a set of parameters and flags that determine
how the export should be executed.
These parameters and flags are contained in a PDFExportParams
class instance.
PDF export parameters are listed in the table below.
Export parameter name | Description | Get-method | Set-method |
---|---|---|---|
Database for export | A pointer to a database to be exported to a .pdf file. |
database()
|
setDatabase()
|
Output stream for writing to .pdf file | A reference to an OdStreamBuff pointer, representing the output stream object to be used for writing data to a .pdf file. |
output()
|
setOutput()
|
Version |
Version of the output .pdf file. See the list of supported versions in the
PDFExportVersions
enumeration.
|
version()
|
setVersion()
|
Layouts to export | Array of the layouts that are exported to the output .pdf file. If the array has no elements, only the active layout is exported. See Export Layouts and Set Page Parameters for more information. |
layouts()
|
setLayouts()
|
Page parameters | Array of the page parameters (paper size, margins, etc.) of the exported layouts. Count of elements must be equal to the count of the elements of the layout array. See Export Layouts and Set Page Parameters for more information. |
pageParams()
|
setPageParams()
|
Background color | Background color of the output .pdf file. White is the default value. |
background()
|
setBackground()
|
Palette | Palette for the output .pdf file. If not specified (NULL), one of two default palettes are used depending on the background color. |
palette()
|
setPalette()
|
Color policy | Color policy used for creating export output. See Export to a Monochrome or a Grayscale .pdf File for details. |
colorPolicy()
|
setColorPolicy()
|
Vectorizing resolution | Resolution used for vectorizing the output .pdf file (in dots per inch, DPI). Standard values are: 72, 150, 200, 300, 400, 600, 720, 1200, 2400 and 4800 DPI. Default value is 600 DPI. |
getGeomDPI()
|
setGeomDPI()
|
Hatch export resolution | Resolution for images created during hatch export (in dots per inch, DPI). See Export Hatches for details. |
hatchDPI()
|
setHatchDPI()
|
Resolution for color and grayscale images | Resolution for exported color and grayscale images (in dots per inch, DPI). |
colorImagesDPI()
|
setColorImagesDPI()
|
Resolution for monochrome images | Resolution for exported monochrome images (in dots per inch, DPI). |
bwImagesDPI()
|
setBWImagesDPI()
|
Image cropping | Determines how clipped images are exported. An image can be clipped by a clipping boundary (for example, by the boundary of a page in a .pdf file or by a viewport boundary). If equal to false, clipped images are exported as full images; in the other case only the visible part of images are exported. |
imageCropping()
|
setImageCropping()
|
Image DCT compression | Determines whether the Discrete Cosine Transformation (DCT) compression algorithm is used for exporting images. If the value is equal to true, images are represented in the JPEG format. Using DCT compression significantly reduces of the output .pdf file size. |
dctCompression()
|
setDCTCompression()
|
Image DCT compression quality | Determines the quality of image DCT compression (JPEG format) and is applied only if the Image DCT parameter is equal to true. The parameter value can be between 10 and 100 and determines the quality of the compressed image relative to the original image. The default value is 50. |
dctQuality()
|
setDCTQuality()
|
Solid hatch export type | Algorithm used for exporting solid hatches. See Export Hatches for details. |
solidHatchesExportType()
|
setSolidHatchesExportType()
|
Gradient hatch export type | Algorithm used for exporting gradient hatches. See Export Hatches for details. |
gradientHatchesExportType()
|
setGradientHatchesExportType()
|
Other hatch export type | Algorithm used for exporting non-solid and non-gradient hatches. See Export Hatches for details. |
otherHatchesExportType()
|
setOtherHatchesExportType()
|
Output document's title | Title of the output .pdf file. |
title()
|
setTitle()
|
Output document's author | Name of the person who created the output .pdf file. |
author()
|
setAuthor()
|
Output document's subject | Subject of the output .pdf file. |
subject()
|
setSubject()
|
Output document's keywords | Keywords associated with the output .pdf file. |
keywords()
|
setKeywords()
|
Output document's creator | Name of the application (for example, Adobe® FrameMaker®) that was used to create the original drawing document. |
creator()
|
setCreator()
|
Output document's producer | Name of the application (for example, Adobe Acrobat® Distiller) that was used to convert the original drawing to the output .pdf file. |
producer()
|
setProducer()
|
PRC support | Determines how PRC format is supported during the export process. See PRC Support for more information. |
PRCMode()
|
setPRCMode()
|
PRC compression | Determines whether compression for PRC data is supported during the export process. You can separately set the compression level for both B-Rep and tessellation data. See PRC Support for more information. |
PRCCompression()
|
setPRCCompression()
|
PRC context | Contains the PRC data to export, which can be filtered to include specific entities to export into a PRC stream. See PRC Support for more information. |
getPRCContext()
|
setPRCContext()
|
PRC background color |
Defines the background color of PRC data created as a result of the export operation.
To determine whether the background color differs from the default color white,
use the hasPrcBackground() method.
To return the default background color for PRC data, call the
clearPrcBackground() method.
See PRC Support for more information.
|
getPrcBackground()
|
setPrcBackground()
|
PRC rendering mode | Defines the rendering mode for the exported PRC content. |
getPrcRenderingMode()
|
setPrcRenderingMode()
|
Shaded viewport export | Determines the export mode for viewports in shaded rendering mode. See Export of Shaded Viewports for details. |
shadedVpExportMode()
|
setShadedVpExportMode()
|
Transparency of shaded views background |
This parameter determines whether backgrounds of shaded views exported with a GS device are transparent.
The true value indicates transparency; the false value indicates opaqueness.
|
transparentShadedVpBg()
|
setTransparentShadedVpBg()
|
Disable GS device | Disables the GS device that is used for exporting shaded views. If the parameter value is equal to true, the GS device is disabled; otherwise (by default) the GS device is enabled. ODA Software supports exporting to PDF as geometry for wireframe and for wireframe with hidden lines (if the hidden lines removal algorithm is switched on). For other rendering modes (for example, shaded), the content is exported as an image, which is inserted into an output .pdf file afterward. Although for particular circumstances, the drawing can have the same look for different rendering modes (for example, a circle for wireframe and shaded modes). In such cases, exporting a drawing as an image has a disadvantage when scaling the output PDF content. Therefore it is better to export such entities as geometry despite the rendering mode. To do it, switch off the GS device (set the option equal to true) and the drawing content will be exported as geometry without dependency on the rendering mode. However, using this option can cause an incorrect rendering result in the output PDF document, so be careful. In general, it is NOT recommended to disable the GS device used for the export process. |
forceDisableGsDevice()
|
setForceDisableGsDevice()
|
GSCache Usage | Determines whether GsCache is used within a PDF export operation. For additional information see the Use GsCache During Export section. |
useGsCache()
|
setUseGsCache()
|
Export with searchable text |
Determines whether text from an original drawing
can be searched in the output .pdf file. This parameter is used only if text with a SHX or TTF font is exported
as geometry. This parameter can accept one of four values:
For each searchable text entity represented as geometry, an annotation that contains the text content of the entity is added. |
searchableTextType()
|
setSearchableTextType()
|
Using view extents | Determines whether the export process should use view extents (if equal to true) or not (if equal to false). If this flag is set to true, the view extents are used instead of plot extents (which is used by default) when calculating the exported drawing extents. A drawing can contain entities that are considered in the calculation of the extents, but these entities are not rendered (for example, an empty multiline text entity, entities on hidden layers, etc.). View extents mode (flag is true) assumes that all invisible entities are taken into account when extents are calculated. Plot extents mode (flag is false) assumes that such entities are excluded from the extents calculations. |
useViewExtents()
|
setUseViewExtents()
|
Watermarks | Contains an array of watermarks associated with the output PDF document. See Work with Watermarks for more information. |
watermarks()
|
addWatermark()
|
The PDF export flags are stored in the
setExportFlags()
enumerator, which is
a member of the PDFExportParams
class.
PDF export options are determined by the parameters' values and combination of parameter flags.
Default combination of export flags is
kTTFTextAsGeometry|kSHXTextAsGeometry|kFlateCompression|kASCIIHexEncoding|kZoomToExtentsMode
, i.e.:
Some export flags are not recommended for use because they are deprecated or can be removed or changed in the next versions of the ODA Platform. See Deprecated Export Flags for details.
PDF export flags are described in the following table.
Export parameter | Parameter name | Value | Description |
---|---|---|---|
Use embedded TTF | kEmbededTTF | 1 | Enable embedding of True Type font files in the .pdf file. See Export Fonts for more information. |
TTF text as geometry | kTTFTextAsGeometry | 2 | Enable True Type font text to geometry conversion. See Export Fonts for more information. |
SHX text as geometry | kSHXTextAsGeometry | 4 | Enable SHX font text to geometry conversion. See Export Fonts for more information. |
Use geometry optimization | kSimpleGeomOptimization | 8 | Determines whether simple geometry optimization is enabled during the export process (separated segments combined to one polyline, Bezier curve control points). See Geometry Optimization for more information. |
Enable layers support | kEnableLayers | 16 | Determines whether layer support is enabled, in which case layers are added to the output .pdf file. See Export Layers for more information. |
Include invisible layers | kIncludeOffLayers | 32 | Determines whether invisible layers of the exported drawing are added to the output .pdf file. See Export Layers for more information. |
Embedded TTF optimization | kEmbededOptimizedTTF | 64 | Enables reducing the True Type font file size that is embedded in the output .pdf file. See Export Fonts for more information. |
Use hidden lines removal algorithm | kUseHLR | 128 | Determines whether software vector hidden-line removal (HLR) is used to delete hidden lines during the export process for corresponding viewports. If this flag is equal to true, the drawing contents in wireframe mode is exported as geometry. If it is equal to false, the content is exported as an image. |
Data compression | kFlateCompression | 256 | Determines whether a data compression algorithm is applied when writing drawing data in the internal PDF stream. See Use Data Compression and Hexadecimal Format for more information. |
Hexadecimal encoding | kASCIIHexEncoding | 512 | Determines whether data is written in the internal PDF stream as hexadecimal format. See Use Data Compression and Hexadecimal Format for more information. |
Exporting hyper links support | kExportHyperlinks | 1024 | Enables exporting hyperlinks to the output .pdf file. |
Zoom to extents mode | kZoomToExtentsMode | 2048 | Determines whether the exported drawing is in the Zoom to Extents mode. If enabled, the layout geometry will be zoomed to the paper size, otherwise layout settings are applied. |
Create a linearized .pdf file | kLinearized | 4096 | Determines whether the export process creates a linearized .pdf file from the exported drawing. See Export to a Linearized .pdf File for more information. |
Merge crossing lines colors | kMergeLines | 8192 | Determines whether the colors of crossing lines are merged. |
Measuring scale | kMeasuring | 16384 | Determines whether the measuring scale is implemented for the entities in the output .pdf file. |
Special values of flags can also be used:
kZeroFlag
(0) means that all flags are disabled.
kDefault
stores the default value of the flag combination.
To get the current combination of export flags, use the
exportFlags()
method of the PDFExportParams
class.
To set a new combination of export flags as the current one, use the
setExportFlags()
method of the PDFExportParams
class.
Each drawing has one or several layouts that represent model space or paper space. To export specified layouts to the output .pdf file, add the layout name in the array: Layouts to export. If the array is empty, only the active layout is exported. Page count of the output .pdf file depends on the element count in this array.
The ability to set page parameters for the output .pdf file depends on whether Zoom to Extents mode is switched on or off:
Layers in the original drawing can be visible (switched on) or hidden (switched off). To enable processing of layers during the export to PDF, the Enable Layers Support flag must be switched on. Also, the user can control the export of invisible layers using the Include Invisible Layers flag.
Note that exporting layers depends on the rendering mode of the original drawing: if it is rendered in wireframe mode (with or without the hidden lines removal algorithm), the output PDF document also contains layers (if Enable Layers Support is switched on of course). For other rendering modes, layer export is not supported because the content is exported as an image.
The Use Geometry Optimization flag determines whether simple geometry optimization is used when a drawing is exported to a .pdf file. Simple geometry optimization uses a more effective mechanism of drawing document elements (drawing one polyline instead of several separated segments, Bezier curve control points, and so on). For example, if optimization is not used, a rectangle is drawn with four commands: one for each line. When optimization is used, a rectangle is drawn with a single command, thus reducing the overall size of the output file.
There are three font types that can be used for text:
Text from the original drawing can be exported to PDF either with geometry (when symbols are drawn as collections of primitives) or with internal facilities of the PDF format. The TTF Text as Geometry flag enables True Type font text to geometry conversion (when switched on), and the SHX Text as Geometry flag enables SHX font text to geometry conversion. These flags can affect the size of the output .pdf file. The effect depends on the quantity of text elements in the source database.
Additionally, a font file can be included in the output .pdf file or the document may contain only a reference to a font file. In the first case a font is called embedded, and the text can be drawn even if the specified font is not installed for the operating system. In the second case the font must be installed on the operating system for the correct text to display in the output .pdf file. If the Use Embedded TTF flag is on, embedded fonts are used for text display. Using embedded fonts causes a large increase of output file size but guarantees that the text can be correctly displayed in the resulting .pdf file. Using embedded fonts also makes the output .pdf file more portable.
The Embedded TTF Optimization flag reduces the size of the output .pdf file by removing unused parts of the fonts (for example, characters that are never used in the text). However, embedded font optimization restricts editing abilities.
For additional information about handling fonts, see Font Handling.
There are three kinds of hatches (as you can see in the picture below):
Export operations can differ depending on what kind of hatch is exported.
There are three ways of exporting hatches to PDF (using the ExportHatchesType
enumerator):
kPdfPaths
enumerator value) — Results
in a smaller .pdf file size than other methods and avoids distortion of graphical
elements. This algorithm exports only the outer loop of the hatch and then
fills this loop with the appropriate color.
kDrawing
enumerator value) —
Divides the hatch into many triangles; each can contain its own color.
This leads to a larger output file size.
kBitmap
enumerator value) — Realizes hatches
as a bitmap picture. The result of exporting a hatch as a bitmap looks smoother
than as a vectorizer and often has a smaller output file size. The output
file size strongly depends on the DPI (Dots Per Inch) resolution specified
for the export process. Increasing DPI provides better quality but a larger
output file.
hatchDPI()
method of the PDFExportParams
class.
setHatchDPI()
method of the PDFExportParams
class.
The PDF path export algorithm can be applied only to solid hatches, not gradient or pattern hatches. In those cases, bitmap export is automatically applied.
To get the current type of solid hatch for exporting, use the solidHatchesExportType()
method of the PDFExportParams
class.
To set a new type of solid hatch for exporting, use the
setSolidHatchesExportType()
method of the PDFExportParams
class.
Bitmap and vectorizer export can be applied to hatches of any type.
To get the current type of gradient hatch for exporting, use the
gradientHatchesExportType()
method of the PDFExportParams
class.
To set a new type of gradient hatch for exporting, use the
setGradientHatchesExportType()
method of the PDFExportParams
class.
To get the current type of pattern hatch for exporting, use the
otherHatchesExportType()
method of the PDFExportParams
class. To set a new type of pattern hatch for exporting, use the
setOtherHatchesExportType()
method of the PDFExportParams
class.
The quality of exported hatches for vectorizer and PDF path export types depends on the resolution (DPI) used for vectorizing.
To get the current vectorizer resolution, use the
getGeomDPI()
method of the PDFExportParams
class.
To set a new vectorizer resolution, use the setOtherGeomDPI()
method of the PDFExportParams
class.
The Data Compression flag determines whether data compression is used during PDF export. If the flag is on, internal PDF compression algorithm is used. Data compression reduces the size of the output .pdf file.
Also, drawing data can be written in the .pdf file stream in hexadecimal format. If you do so, you can then explore the output file with hex-editors. For hexadecimal support, switch on the Hexadecimal Encoding parameter.
Remember that using hexadecimal support leads to doubling of the output file size.
You can export an original drawing to a monochrome or grayscale .pdf file
by setting the color policy of the PDFExportParams
class.
The color policy can be set with the method
setColorPolicy()
.
To retrieve the current color policy, use the
colorPolicy()
method.
To represent the color policy, the
ColorPolicy
enumeration is used:
kNoPolicy
— No color policy is used. A drawing is exported with its native
color palette (as is). This is the default value.
kMono
— Drawing is exported to a monochrome .pdf file.
kGrayscale
— Drawing is exported to a grayscale .pdf file. Native colors
are converted into grayscale.
A monochrome .pdf file can also be produced by setting a monochrome plot style to the layout of the original drawing. This converts a colored drawing into a monochrome .pdf file.
A plot style is a file containing rules that determine how the colors of a drawing should be converted, in this case into monochrome, i.e. which gray gradient each color must be replaced with. To export to monochrome, specify the path to the plot style file(s) so the export program can access them.
The path to a monochrome plot style file can be set via the DDPLOTSTYLEPATHS
system variable, and then the plot style can be applied to one of the drawing layouts:
bool bMonochrome(false);
// Validator creates stylesheets equal to .ctb, .stb files. It's fully depends on DDPLOTSTYLEPATHS env var.
OdDbPlotSettingsValidatorPtr pValidator = svcs.plotSettingsValidator();
// Get database plot style mode: color-dependent or named
int i = pDb->getPSTYLEMODE();
OdString strMono((i == 1) ? "monochrome.ctb" : "monochrome.stb");
if(bMonoPalette)
{
OdArray <const OdChar*> PSSlist ;
pValidator->plotStyleSheetList(PSSlist);
unsigned int iSize = PSSlist.size();
if (iSize == 0)
{
STD(cout) << "Monochrome mode required files: monochrome.ctb, monochrome.stb to be found. Now exiting." << STD(endl);
return 2;
}
const OdChar* mono = strMono.c_str();
for(unsigned int i = 0; i < iSize; ++i)
{
if (*mono == *PSSlist[i])
{
bMonochrome = true;
break;
}
}
}
if (bMonochrome)
{
OdDbDictionaryPtr pLayoutDict = pDb->getLayoutDictionaryId().safeOpenObject();
for(unsigned f=0; f < params.layouts().size(); ++f)
{
OdDbLayoutPtr pLayout = pLayoutDict->getAt(params.layouts()[f]).safeOpenObject(OdDb::kForWrite);
pValidator->setCurrentStyleSheet((OdDbPlotSettings*)pLayout, strMono);
}
}
Also, the resolution of the monochrome images for the output .pdf file can be specified;
the setBWImagesDPI()
method is used to set the resolution, and
bwImagesDPI()
is used to get the current resolution.
Exporting a drawing to a monochrome or grayscale .pdf file using plot styles has several disadvantages:
ODA Platform supports exporting 3D entities to 3D PDF format (PRC format).
PRC support can be handled with the
PRCMode()
and setPRCMode()
methods of the PDFExportParams
class.
The value returned by PRCMode()
or passed to setPRCMode()
is a value of the PRCSupport
enumeration:
kDisabled (0)
— Export to PRC is disabled.
kAsBrep (1)
— Export to PRC is supported as a B-Rep.
kAsMesh (2)
— Export to PRC is supported as a mesh.
Note that you cannot turn on PRC support mode and use hidden lines removal algorithm (HLR) at the same time.
PRC data can be exported using a compression algorithm. To set the compression level, use the
setPRCCompression()
method. This method accepts three parameters:
compressionLevel
—
Determines what kind of compression algorithm is applied during the export process.
bCompressBrep
— A flag that controls compression of B-Rep data.
If the value is equal to true, the data is compressed.
bCompressTessellation
— A flag that controls compression of tessellation data.
If the value is equal to true, the data is compressed.
The compression level parameter can be one of the following values:
kA3DLooseCompression (0)
— Compression with 0.001 mm tolerance.
kA3DMeddiumCompression (1)
— Compression with 0.01 mm tolerance.
kA3DHighCompression (2)
— Compression with 0.1 mm tolerance.
To get the current state of the compression option for PRC data, use the
PRCCompression()
method.
Note that this method doesn't return compression flags for B-Rep and tessellation data. It returns only the current compression level value. Therefore, be sure to set the B-Rep and (or) tessellation flags to the appropriate values before executing the export process.
To check whether the compression algorithm is used for B-Rep and tessellation data,
use the hasPrcBrepCompression()
and hasPrcTessellationCompression()
methods
of the PDFExportParams
class respectively.
A PRC export context is represented by the OdPrcContextForPdfExport
class,
derived from OdRxObject
. This class contains:
shouldExportAsPRC()
, which determines whether a specified graphical object should be rendered
as .prc data in the output .pdf file. Default implementation returns false.
The OdPrcContextForPdfExport
class is declared and defined in
/Kernel/Exports/PdfExport/Include/PrcContextForPdfExport.h
.
ODA Platform provides several types of PRC contexts, as described in the following table.
PRC Context Name | Function for Creating Context | Description |
---|---|---|
OdPrcContextForPdfExport_AllInSingleView
|
odCreatePrcAllInSingleViewContextForTD()
|
Implements single view mode: exports all entities located in one view of a drawing database into a .prc stream of the output .pdf file. |
OdPrcContextForPdfExport_OnlySolidsMultiView
|
odCreatePrcOnlySolidsMultiViewContextForTD()
|
Implements one view per solid entity mode: exports each solid entity located in an individual view into a .prc stream of the output .pdf file; 2D geometry is exported into .pdf content. |
OdPrcContextForPdfExport_OnlySolidsSingleView
|
odCreatePrcOnlySolidsSingleViewContextForTD()
|
Implements single view for solids mode: exports all solid entities located in one view into a .prc stream of the output .pdf file. 2D geometry is exported into .pdf content. |
OdPrcContextForPdfExport_Default
|
odCreatePrcDefaultContextForTD()
|
Implements one view per entity mode: exports each entity located in an individual view into a .prc stream of the output .pdf file. |
OdPrcContextForPdfExport_AllInSingleView_DGN
|
odCreatePrcAllInSingleViewContextForDGN()
|
Implements one view per entity mode for .dgn files: exports all entities located in one view of a drawing database into a .prc stream of the output .pdf file. |
Functions for .dwg drawings are defined in the
/Prc/Export/PrcExport/Include/PrcContextForPdfExportImpl.h
header file.
Functions for .dgn drawings are defined in the
/Prc/Export/Dgn2PrcExport/Include/PrcContextForPdfExportImpl.h
header file.
Each type of PRC context is implemented as a successor of the OdPrcContextForPdfExport
class. Each PRC context sub-class has its own implementation of the shouldExportAsPRC()
method to define whether an entity should be exported into a .prc stream and
to determine the viewport's index for it. PRC context sub-classes are registered
in the ODA environment while creating an instance of PrcExportModule
(for
.dwg files) or OdDgn2PrcExportModule
(for .dgn files).
To get the current PRC context containing user PRC data that should be used
for the export process, call the getPRCContext()
method. To set a new PRC context, use the setPRCContext()
method.
PDF export functionality allows you to set a background color for PRC data created within the export process.
By default, PRC data has a white background color. To set a new background color, use the setPrcBackground()
method of the PDFExportParams
class.
The PDFExportParams
class also provides methods that allow managing the background color:
hasPrcBackground()
— Determines whether the PRC data has a background color that differs from the default value (white).
getPrcBackground()
— Retrieves the currently applied PRC background color.
clearPrcBackground()
— Changes the current PRC background color to the default value (white).
Note: According to ISO standards, the PDF/A format is not compatible with the PRC format. Therefore, if both modes (PRC and PDF/A support) are switched on, an exInternalError occurs. See the PDF/A Format Support section for details about exporting with PDF/A support.
Any .pdf file can be partly processed. This means that it is possible to retrieve any portion of bytes from a file to process any particular element (for example, page, link or picture) without downloading and reading other elements of the document.
This technology for .pdf files is similar to streaming audio or video and is called linearization. It provides fast incremental access to .pdf data. Linearization has the following advantages:
To obtain these advantages, a .pdf file should be saved using the linearization algorithm. ODA Platform supports linearization for exporting a drawing to a .pdf file by setting the appropriate flag value.
PDF export functionality supports creating archive .pdf documents (PDF/A).
PDF/A is a specific version of the .pdf format for long-term archival preservation of electronic documents. This format differs from common PDF format by excluding all features that can be dangerous for long-term document storage (for example font linking, encryption, etc.).
PDF/A format is standardized by ISO. ISO requirements for viewer applications contain color management guidelines, embedded fonts support, and a user interface for reading embedded annotations.
There are several versions of PDF/A format:
The difference between PDF/A-2 and PDF/A-3 is insignificant for CAD applications, therefore ODA Platform supports only PDF/A-1 and PDF/A-2 versions.
To specify a version of PDF/A format, the PDF_A_mode
enumeration from the PDFExportParams
class is used.
Note: When exporting drawings into archive PDF format, it is strongly recommended to use the PDF/A-2 version for the following reasons:
MergeControl
parameter
is always set to the LinesOverwrite
value.
To export to the desired version of PDF/A format, use the setArchived()
method of the PDFExportParams
class. To retrieve whether exporting to the archive
.pdf format is enabled, and if enabled, which version of PDF/A format is used,
call the archived()
method of the PDFExportParams
class.
There are several restrictions and disadvantages of using the .pdf archive format for export:
A drawing to be exported may include graphical entities that represent real-world objects. This means that the graphical entities contain specific information about scale and measurement units to store constant data about real-world objects and their relationship with units in user space of the output .pdf file. Such information allows CAD applications to perform measurements that yield results in the units intended by the creator of the document. According to version 1.6 of the PDF format standard, measurement data can be stored in a .pdf file.
For example, a drawing contains a line that is defined with two three-dimensional points: (1000, 1000, 0) and (1100, 1000, 0) and a rectangle around it. It is obvious that the real length of the line is 100 mm:
If you export this drawing to a .pdf file with plot scale 1:1, and then apply a measuring tool in a .pdf reader application, the length of the line is quite close to the original length, for example 99.9 mm.
However, if you use a Fit to Screen plot style for export, the length of the line in the output file has a significantly different value from the original (for example 93.05 mm). This happens because the length of the line depends on the output .pdf file's page size. To keep the correct length, use a scale coefficient to recalculate the line length after applying the resizing operation.
To achieve this, you can use the kMeasuring
flag, declared in the PDFExportFlags
enumerator:
PDFExportParams params;
...
params.setExportFlags(PDFExportParams::PDFExportFlags(PDFExportParams::kMeasuring));
After setting the measuring scale flag, the line length in the .pdf file is equal to or very close to the original value in the drawing.
To get better accuracy of the line length, use better resolution (DPI). For example, when accuracy is 600 dpi, the 100 mm length of the line can be converted to 99.97 mm. If you use 720 dpi or higher resolution, you will get exactly 100 mm length of the line.
ODA SDK supports a shaded rendering mode for 3D figures display. In cases when you want to export such objects in a .pdf file, you can face the issue when a rendering device used for PDF export, cannot render in shaded mode. To solve this issue the PDF export module uses the device that renders the exported drawing on the screen, but redirects the rendering output to a bitmap that is inserted into the resulted .pdf file afterward.
According to this approach, the output bitmap has a very low resolution because, on the one hand, it is necessary to be sure that the graphic device is able to draw the bitmap; on the other hand, different devices have different restrictions for the bitmap size or even for the aspect ratio when an old graphic card is used.
To get more flexible behaviour, PDF export module provides the ability to set the mode of the shaded viewport rendering into one of the
following values (represented with the
PDFShadedViewportExportMode
enumeration):
kExportOnePiece
— Export shaded viewports as one-piece bitmap image with low resolution.
kExportAsStrips
— Export shaded viewports as striped images according to vector resolution (geometry DPI).
kExportAsTiles
— Export shaded viewports as tiled images according to vector resolution (geometry DPI).
The two last modes assume that the viewport is rendered as a set of strips or tiles corresponded to the currently set vector resolution.
The kExportOnePiece
value means that the old way of rendering with creating a tiny bitmap is applied.
kExportAsStrips
mode demonstrates the better performance, when viewing an output .pdf file, than the kExportAsTiles
mode,
but it can lead to problems with rendering on old graphics card in cases when the hardware rendering is used (for example, GLES2 rendering).
Use the shadedVpExportMode()
and the setShadedVpExportMode()
methods for getting and setting of the shaded viewport export options respectively.
ODA Software provides an ability to add watermarks in the resulting PDF document created by the export process and set different options for these watermarks. You can find detailed information about this opportunity below.
Any object of the PDFExportParams
class can contain an array of Watermark
instances,
can add new watermarks to the array, and remove all watermarks from the array.
To manage watermarks, the PDFExportParams
class provides the following interface:
addWatermark()
— Add a new watermark object to the array of watermarks.
watermarks()
— Retrieves all previously added watermarks.
clearWatermarks()
— Removes all watermarks from the object.
Watermark parameters are represented with the Watermark
structure that stores watermark properties:
WatermarkFonts
enumeration.
Watermark watermark;
watermark.text = L"ODA Platform";
watermark.font = Watermark::kTimesRoman; //default value - Times Roman
watermark.color = ODRGB(255, 0, 0); //default value – black
watermark.fontSize = 24; //default value – 48
watermark.opacity = 75; //default value - 50%
WatermarkPosition
enumeration data type
(the following pictures and code fragment illustrate how a watermark looks in each position):
watermark.position = Watermark:: kUpperLeftToLowerRight;
The position for the code fragment is represented at figure f.
A watermark can also be fitted to the page size by setting the corresponding flag from the Watermark
structure.
The picture below shows how the watermark looks when it is fitted to the page (depending on the position).
The following code fragment shows how a watermark can be fitted to the page like at figure d:
watermark.color = ODRGB(255, 0, 0);
watermark.opacity = 75;
watermark.text = L"ODA Platform";
watermark.position = Watermark:: kUpperLeftToLowerRight;
and set the scaling option: Font size in this case will be calculated automatically.
watermark.scaleToPage = true;
Note that you can add several watermarks to the PDFExportParams
object like the following code fragment illustrates:
PDFExportParams params;
Watermark watermark;
watermark.font = Watermark::kTimesRoman; //default value - Times Roman
watermark.color = ODRGB(255, 0, 0); //default value – black
watermark.fontSize = 24; //default value – 48
watermark.opacity = 75; //default value - 50%
Set watermark text:
watermark.text = L"Watermark example 1";
watermark.position = Watermark::kUpperRight; //default - left to right in the page center
//Add the first watermark
params.addWatermark(watermark);
//Change the options of the watermark
watermark.color = ODRGB(0, 0, 255);
watermark.opacity = 50;
watermark.text = L"Scaled watermark example";
watermark.position = Watermark:: kUpperLeftToLowerRight;
//set the scaling option: Font size in this case will be calculated automatically.
watermark.scaleToPage = true;
//Add the second watermark:
params.addWatermark(watermark);
The resulted .pdf file is shown in the picture below:
In the OdaMfcApp
sample application, you can specify watermark options for PDF export using the Export to PDF
dialog:
Click Custom properties
to open the additional export options dialog:
In the Watermark
section, specify the watermark text, text font, font size, text color, watermark position, and opacity.
It takes a long time to render a complex drawing that contains many entities joint in blocks. To speed up the rendering process, the GsCache option of the graphic system can be used.
Since the ODA SDK 2021.8 version, the GsCache option can also be used for increasing the speed of the PDF export process as well. It significantly affects the time of the export procedure by decreasing the time from about a quarter for medium block to several times for a very complicated drawing.
To use the GsCache option for the PDF export, set the related options like in the code fragment below:
PDFExportParams params;
params.setExportFlags(PDFExportParams::kFlateCompression);
params.setUseGsCache(true);
Please pay attention to the disadvantage of GsCache option usage for exporting drawings, which contain a large number of entities not combined into blocks: use of the option, in this case, may cause the export time increase in comparison with exporting without GsCache.
Do not use m_reserved1, m_reserved2, m_reserved3, or m_reserved4 flags because they are deprecated and can be changed or deleted in future versions of the ODA Platform.
Export Several Drawings into One .pdf File
Copyright © 2002 – 2020. Open Design Alliance. All rights reserved.
|