The “Hello World” Example

The “Hello World” example is found in ./samples/publish/publishsource/HelloWorld.

It creates a new PDF document and inserts a PRC file with a 3D representation of the text “hello world” into it.

The PDF, sample_HelloWorld.pdf, is placed in ./samples/publish/publishgallery. Note that the following description omits starting up and shutting down HOOPS Publish, which is described in the HOOPS Publish Programming guide.

Default Input and Output Files

When run with no command line arguments the following definitions are used to define the relevant input and output files. Note the working directory is set to IN_INSTALL_DIR at the top of the main() function.

#ifdef _WIN64
#define IN_INSTALL_DIR _T("..\\..\\..\\..\\bin\\win64\\")
#elif defined _WIN32
#define IN_INSTALL_DIR _T("..\\..\\..\\..\\bin\\win32\\")
#else
#error "Architecture not supported!"
#endif
// WARNING: with the SetCurrentDirectory solution, data directory is "..\\..\\samples\\data"
#define IN_3DFILE   "..\\..\\samples\\data\\step\\helloworld.stp"
#define IN_POSTERIMAGE   "..\\..\\samples\\data\\images\\empty.jpg"
#define IN_JSFILE   ""
#define OUT_FILE    "..\\..\\samples\\publish\\publishgallery\\sample_HelloWorld.pdf"

Adding a License Key

You must provide your license to HOOPS Publish by a call of A3DLicPutUnifiedLicense(). Usually, our example codes are provided the license string through a macro definition called HOOPS_LICENSE:

A3DLicPutUnifiedLicense(HOOPS_LICENSE);

Creating a PDF Document And Page

A new document is created and a page is added in standard US Letter format.

// create empty document
A3DPDFDocument* pDoc = NULL;
iRet = A3DPDFDocumentCreateEmpty(&pDoc);
CHECK_RET;

if(pDoc != NULL)
{
   // creating a document page from scratch
   A3DPDFPageData2 sPageData;

   A3D_INITIALIZE_DATA(A3DPDFPageData2, sPageData);

   sPageData.m_ePageOrientation = kA3DPDFPageLandscape;
   sPageData.m_ePageSize = kA3DPDFPageLetter;  // standard letter format: 612 x 792
   constintiPageWidth = 792, iPageHeight = 612;
   A3DPDFPage* pPage = NULL;
   iRet = A3DPDFDocumentAppendNewPage2(pDoc, &sPageData, &pPage);
   CHECK_RET;

The macro A3D_INITIALIZE_DATA is the standard method for initialising HOOPS Publish structures.

Loading the File and Creating the PRC Stream

The PRC File is loaded using:

A3DAsmModelFileLoadFromFile(in_3dfile, &sReadParam, &pModelFile);

The structure sReadParam is of type :cpp:struct:A3DRWParamsLoadData and has multiple flags that control how the file is loaded, what is read, how it is tessellated etc. These are documented in the API Reference.

If the load was successful then a PRC Stream is created from the model file entity

if(pModelFile)
{
   // creating the PRC stream from the model file
   // that is going to be inserted into the PDF file
   A3DRWParamsExportPrcData sParamsExportData;
   A3D_INITIALIZE_DATA(A3DRWParamsExportPrcData, sParamsExportData);
   iRet = A3DPDF3DStreamCreateFromModelFileAsPRC(pDoc,
      pModelFile,
      &sParamsExportData,
      &pStream, NULL);
   CHECK_RET;

Adding a Poster Image

A poster image is a raster representation of the 3D annotation that is displayed when the annotation is not activated. By default user interaction is needed to activate a 3D annotation, although activation can also happen automatically when the document is opened. If no poster image is specified when a 3D annotation is created, HOOPS Publish will automatically generate one.

// creating a poster image to be used as a poster for 3D.
A3DPDFImage* pImage = NULL;
A3DPDFImageCreateFromFile(pDoc, in_posterfile, kA3DPDFImageFormatJpg, &pImage);

The image defined in pImage is added to the annotation as the poster image as the m_pPosterImage parameter of the A3DPDF3DAnnotData structure passed when the 3D Annotation is created - see Creating the 3D Annotation.

Creating the 3D Artwork

The ’artwork’ for the annotation represents the model (the stream), and Javascript and the named views (stored camera parameters).

// creating the 3D artwork
A3DPDF3DArtwork* p3DArtwork;
A3DPDF3DArtworkData2 s3DArtworkData;
A3D_INITIALIZE_DATA(A3DPDF3DArtworkData2, s3DArtworkData);
s3DArtworkData.m_pStream = pStream;
s3DArtworkData.m_eAnimationStyle = kA3DPDFAnimStyleNoAnimation;
iRet = A3DPDF3DArtworkCreate2(pDoc, &s3DArtworkData, &p3DArtwork);
CHECK_RET;

Creating the 3D Annotation

After adding the stream to the artwork, the 3D annotation can be created. A number of parameters that can control how the annotation looks can be set:

A3DPDF3DAnnotData sAnnotData;
A3D_INITIALIZE_DATA(A3DPDF3DAnnotData, sAnnotData);
sAnnotData.m_bOpenModelTree = false;
sAnnotData.m_bShowToolbar = false;
sAnnotData.m_eLighting = kA3DPDFLightCADOptimized;
AnnotData.m_eRenderingStyle = kA3DPDFRenderingSolid;
sAnnotData.m_sBackgroundColor.m_dRed = 0.25;
sAnnotData.m_sBackgroundColor.m_dGreen = 0.25;
sAnnotData.m_sBackgroundColor.m_dBlue = 0.25;
sAnnotData.m_bTransparentBackground = false;
sAnnotData.m_eActivateWhen = kA3DPDFActivPageOpened;
sAnnotData.m_eDesactivateWhen = kA3DPDFActivPageClosed;
sAnnotData.m_iAppearanceBorderWidth = 0;
sAnnotData.m_pPosterImage = pImage;
sAnnotData.m_p3DArtwork = p3DArtwork;
A3DPDF3DAnnot* p3DAnnot = NULL;
iRet = A3DPDF3DAnnotCreate(pDoc, &sAnnotData, &p3DAnnot);
CHECK_RET;

Inserting the 3D Annotation in the Page

The annotation position is described via a rectangle with the coordinate origin at the bottom left of the page. In the example below the annotation covers the entire page.

if(p3DAnnot != NULL)
{
   // position the 3D annotation in the page
   A3DPDFRectData sPos;
   A3D_INITIALIZE_DATA(A3DPDFRectData, sPos);

   // coordinates are from bottom left of the page
   sPos.m_iLeft = 0;              // lower left x
   sPos.m_iBottom = 0;            // lower left y
   sPos.m_iRight = iPageWidth;    // upper right x
   sPos.m_iTop = iPageHeight;     // upper right y
   iRet = A3DPDFPageInsert3DAnnot(pPage, p3DAnnot, &sPos);
   CHECK_RET;
}

Cleaning Up

To clean up, the model file must be deleted, although this should not be done before the Artwork has been created as it is at this point that the actual conversion takes place. The modified PDF document must then be saved and closed.

// cleaning up
// WARNING: DO NOT CALL THIS BEFORE A3DPDF3DArtworkCreate!
iRet = A3DAsmModelFileDelete(pModelFile);
CHECK_RET;

// saving the document with optimization option
iRet = A3DPDFDocumentSaveEx(pDoc, kA3DPDFSaveFull|kA3DPDFSaveOptimized, out_pdffile);
CHECK_RET;
iRet = A3DPDFDocumentClose(pDoc);
CHECK_RET;