2 Working with a PDF document

HOOPS Publish Entities and Relationships

Document:

Page

3D Annotation

Stream

Artwork

Text

Image

View

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.

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.

A3DPDFDocument* pDoc = NULL;
A3DPDFPageData sPageData;
sPageData.m_ePageSize = kA3DPDFPageLetter; // standard letter format: 612 x 792
A3DPDFPage* pPage = NULL;
iRet = A3DPDFDocumentAppendNewPage(pDoc, &sPageData, &pPage);

Or

A3DPDFPage* pPage = NULL;
A3DInt32 indexpage, nbpages;
iRet = A3DPDFDocumentAppendPageFromPDFFileEx(pDoc, "c:\\temp\\mypdf.pdf", false, &pPage);
iRet = A3DPDFDocumentGetNumberPages(pDoc, &nbpages);
for (indexpage = 0; indexpage < nbpages; indexpage++)
{
iRet = A3DPDFDocumentGetPage(pDoc, indexpage, &pPage);
}

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.

sInformationData.m_pcTitle = "Sample with 3D defined from a PRC file";
sInformationData.m_pcCreator = "HOOPS Publish Sample Application";
sInformationData.m_pcSubject = "This sample shows how to create a 3D PDF defined from a PRC file";
sInformationData.m_pcAuthor = "Tech Soft 3D";
iRet = A3DPDFDocumentSetInformation(pDoc, &sInformationData);

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.

iRet = A3DPDFDocumentAddFileAttachment(pDoc, "c:\\temp\\myinput.prc", "Original PRC file");

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:

function set_all_visible(visible)
{
var materials = scene.materials;
for(i=0; i&ltmaterials.count; i++ )
{
var mat = materials.getByIndex(i);
if( mat != null )
mat.opacity = (visible?1:.05);
}
}
function show_node(name)
{
var node = scene.nodes.getByName(name);
if(node.material != null )
{
node.material.opacity = 1;
}
}

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.

#define IN_PDFFILE "..\\..\\samples\\publish\\publishquickstarts\\Templates\\BillOfMaterials\\BOM_LetterTable_P.pdf"
// insert page from a template file
A3DPDFPage* pPage = NULL;
// the false boolean keeps the same fields names
iRet = A3DPDFDocumentAppendPageFromPDFFileEx(pDoc, in_pdftemplatefile, false, &pPage);
CHECK_RET;

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.

// populating the field with the 3D annotation
iRet = A3DPDFPageFieldSet3DAnnot(pPage, "My3DWindow", p3DAnnot);
CHECK_RET;

Similarly, we can populate the table view below the 3D annotation with text values ...

iRet = A3DPDFPageFieldTextSetValue(pPage, "Part NoRow1", "FG452322");
CHECK_RET;
iRet = A3DPDFPageFieldTextSetValue(pPage, "Part NoRow2", "FG997452");
CHECK_RET;
iRet = A3DPDFPageFieldTextSetValue(pPage, "Part NoRow3", "FG664452");
CHECK_RET;
iRet = A3DPDFPageFieldTextSetValue(pPage, "Part NoRow4", "AG876452");
CHECK_RET;
iRet = A3DPDFPageFieldTextSetValue(pPage, "Part NoRow5", "HFG78452");
CHECK_RET;

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.

iRet = A3DPDFDocumentSetPassword(pDoc, "myuserpassword", "myownerpassword");

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:

iRet = A3DPDFDocumentSave(pDoc, "c:\\temp\\myoutputfile.pdf");

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.

iRet = A3DPDFDocumentClose(pDoc);