2 Working with a PDF document
HOOPS Publish Entities and Relationships
Document:
- Defines a PDF document.
- A new, empty document can be created, or a document can be created using an existing PDF file as a template.
- A document contains a list of pages; new blank pages and pages from existing PDF files can be appended to existing documents.
- Author information can be set for the document, and both a user (reader) and owner (administrator) password can be set.
- External files can be attached to the document and JavaScript can be added that is run when the document is opened.
Page
- A document includes multiple pages.
- Text, images, 3D annotations and other fields can be added to and laid out on pages.
- Tables can also be added on pages.
- Values for fields that have been created via PDF templates can be set via the Page.
- Visibility for fields can be controlled.
- JavaScript, defined as a string, can be attached to fields within the page.
3D Annotation
- A 3D annotation is a container for a particular 3D scene
- 3D annotations contain streams which define the model data and artwork which define the scene when it has been loaded.
- Control is available over when a 3D annotation is activated and deactivated e.g. when the file is opened, or when the user clicks on it.
- Lighting, rendering and animation styles can be set at the annotation level. The animation style refers to how animations are played i.e. automatically or in response to JavaScript.
Stream
- The stream defines the 3D model data which can be in PRC or U3D format.
- A stream is stored on the Artwork in the 3D Annotation.
Artwork
- Artwork optionally contains a reference to a stream, a JavaScript file and an animation style.
- Artwork contains a number of views, which can be created through the HOOPS Publish API or read from the CAD file if present.
Text
- Text can be created with a defined font, size and color, and there is an option to embed the font within the PDF file. Text is positioned when added to a page.
Image
- An image can be created from a wide variety of raster formats. It is placed when added to a page.
View
- A view defines a camera.
- An Artwork within a 3D Annotation can have multiple views. A view can be specified as the default.
- An external name is given from which the view can be accessed via JavaScript.
- As well as camera parameters, a background color, rendering and lighting style can be defined for the view.
- A view can be defined in the source 3D file or programmatically.
PDF Page Layout
PDF documents can be defined with a wide variety of page layout. Here is a description of the different techniques that HOOPS Publish can support. The application sample DemoFunctionalities provided in the HOOPS Publish package illustrates all these variety of page layout definitions.
- Simple page layouts can be defined 'from scratch' entirely using HOOPS Publish functions to create and position different entities such as texts, tables, images, and 3D.
- Some scenarios might require complex page layout and content generated from an external solution. For example, some customers might use Microsoft Excel to generate a PDF with a complex spreadsheet automatically exploded on several pages, or dedicated solutions can generate a rich dashboard and reports with interactive graphs. In this situation, the external solution primarily creates the PDF, then HOOPS Publish is used to open it and enrich it with 3D and other content.
- A PDF page layout can also be defined using PDF Templates. The idea of a PDF Template is to enable the application user to easily customize the PDF page layout, for example by setting a company logo, a specific color scheme, or legal statements. A PDF Template is defined using Adobe Acrobat application and the Acrobat Forms tool. This tool is an interactive tool to create and position some entities on the PDF page. PDF Templates should be provided with the customer application, so that the application user can customize the template if needed. Later, the application uses HOOPS Publish to populate the PDF Template with live data and generate the final PDF. Sample PDF Templates are provided with the HOOPS Publish package and can be a good inspiration for customers to build their own template files.
- The same fields described in the context of PDF Templates might be used in scenarios that require the PDF page to have some interactive fields. The interactive fields must be defined using Acrobat Forms tool and can be populated using HOOPS Publish functions. Interactive fields are list boxes, combo boxes, and buttons and have actions associated that enable an interaction of the field with the 3D or other part of the PDF. For example, selecting an item in a list could populate other fields on the page, or pushing a button could print or send the PDF file to another person.
Creating a PDF document and pages
Using HOOPS Publish functions, the definition of a PDF document can start by creating an empty document (A3DPDFDocumentCreateEmpty), or by using an existing PDF file (A3DPDFDocumentCreateFromPDFFile).
Pages can be appended to any document with A3DPDFDocumentAppendNewPage or A3DPDFDocumentAppendPageFromPDFFileEx (this one should be preferred to import pages from PDF files that contain form fields). A page is determined with a predefined set of formats (A4, letter ...) and an orientation (portrait / landscape). The unit of a page is a point. A point is approximately 1/72 inch.
Pages objects are returned by append functions or can be accessed at any time using A3DPDFDocumentGetNumberPages and A3DPDFDocumentGetPage functions.
Or
Once a page is accessed, functions can be used to create and position entities such as 3D, text, image, table, or link. See insertion functions described in section Inserting data on a page.
Form fields on pages can be populated using the field functions described in section Populating page fields.
The functions A3DPDFPageGetFields and A3DPDFFieldGetInformation can be used to get information on the fields in a page. Ultimately these functions can be useful to dynamically generate reports with only a sub-set of fields selected beyond a large possible list (the application supports hundreds of type of fields, but the end-user only selects a limited number of them to figure in the report).
Enriching a PDF document
PDF document properties
You can set some PDF properties on the document. These properties are shown in the Adobe Reader with the menu File / Properties. To set PDF properties, use the function A3DPDFDocumentSetInformation.
File attachment
You can store files as attached in the PDF file. These attachments are shown in the Adobe Reader with the dedicated panel (accessible with icons on the left). To add a file attachment on the PDF, use the function A3DPDFDocumentAddFileAttachment.
Controlling object transparency
The ProductDescription example uses JavaScript functions defined at document level to make some objects in the scene transparent. Review highlight.js in the ./samples/data/JavaScript directory:
The set_all_visible function iterates all materials in the scene and sets them to be visible or almost invisible (0.05 transparency). The show_node function makes the named node fully opaque.
Templates
If we switch to the BillOfMaterials sample we can see that the PDF file is created using the BOM_LetterTable_P.pdf template is loaded from the ./samples/publish/publishquickstarts/templates/billofmaterials directory.
If we look at the template in Adobe Acrobat Professional, you can see a list of defined field names for each field in the template:
The properties for each of these fields can also be viewed and modified in Adobe Acrobat.
Once the 3D annotation has been created, we can insert it into the "My3DWindow" button in the PDF template using the object's name.
Similarly, we can populate the table view below the 3D annotation with text values ...
The result is sample_BillOfMaterial.pdf:
Securing a PDF document
HOOPS Publish has a function to secure the PDF file with passwords. This is a native functionality of Adobe Reader and a secured PDF file will display a password dialog box when the Reader is initialized.
PDF documents may also be secured defining a permissions field and passing it to the function A3DPDFDocumentSetDocumentPermissions. Among other things, these permissions gives the document author the ability to control whether the document may be edited, saved, copied, or printed. The bit field is documented here.
Compression and saving
HOOPS Publish offers various compression options to reduce file size. The primary compressible parts of a document are the model's B-rep and tessellation, which are controlled by the A3DRWParamsExportPrcData structure. With this data structure, you can control the amount of B-rep compression to use, whether tessellation is compressed (note that tessellation compression is lossy), or you can choose to reduce file size further by completely excluding B-rep from the output file.
The following code sample compresses both B-rep and tessellation:
In addition to the compression options available with the PRC file format, HOOPS Publish automatically compresses the document at the file level, which results in a smaller file size.
At the end of each PDF session, the document needs to be saved. For this, use the function A3DPDFDocumentSave:
Closing a PDF document
Whatever the way the document was opened, it needs to be closed on the end of the working session. During this close, all memory allocated by HOOPS Publish is freed.
