Viewing and Interrogating PDF in the Browser
HOOPS Publish can be used view interactive 3D PDF documents in a browser using standard web technologies without the help of any plug-ins.
This section first addresses how to export a PDF file so it could be viewed inside a browser, followed by a chapter on how to customize our web experience.
No plugin required
Support 3D PDF interactivity
Other Hoops Publish features such as BOM Tables, Carousels are fully supported.
The generated document can be viewed using:
Google Chrome 69+
You may want to check your browser compatibility using this link.
Web Export API
To generate web files from a PDF, use the
A3DRWParamsExportHtmlData data structure and call the method
// This snippet is also part of the sample provided in the package A3DRWParamsExportHtmlData paramsExportData; A3D_INITIALIZE_DATA(A3DRWParamsExportHtmlData, paramsExportData); paramsExportData.m_bIncludeMeasurementInformation = A3D_TRUE; paramsExportData.m_pcHtmlTemplateName = pc3DTemplateFile; paramsExportData.m_eHtmlOutputMode = kA3DWebOnline; paramsExportData.m_ePdfOutputFormat = kA3DWebOutPdfFormatXml; paramsExportData.m_i3dOutputFormat = kA3DWebOutFormatHtml; A3DStatus status = A3DConvertPDFToWebFormat(pcFileName, ¶msExportData, pcOutputDirectory, pcOutputName);
pc3DTemplateFile in this example is a file that will be used as a template for generating HTML files for each 3D annotation in your PDF. It is provided in the HOOPS Publish package.
3 kinds of outputs are available that can be chosen by the variable
A3DRWParamsExportHtmlData.m_eHtmlOutputMode. Each have their own way to be viewed inside a web browser to fill different needs.
kA3DWebOnline: The solution for client/server integration and request for best performances
kA3DWebOfflineSingleFile: The easy way to give a PDF exported to someone.
kA3DWebOfflineWithDependencies: Some middle ground between the two before. No need of a client/server integration, can be easily distributed as long as anyone has some files already setup on their device.
2 kinds of outputs are available that can be chosen by the variable
A3DRWParamsExportHtmlData.m_ePdfOutputFormat. JSon format is a little heavier in disk space but tends to be faster at loading time in the web browser.
kA3DWebOutPdfFormatXml: the PDF structure is generated using an XML format. This is the default value if not explicitly set.
kA3DWebOutPdfFormatJson: the PDF structure is generated using a JSon format.
3 kinds of outputs are available that can be chosen by the variable
A3DRWParamsExportHtmlData.m_i3dOutputFormat. They are not exclusive and can be added on top of each other with operator
|. It allows different stream 3D outputs in one call so that the model can be viewed in different ways.
kA3DWebOutFormatHtml: Each stream 3D is exported as an HTML file. This is the default value if not explicitly set.
kA3DWebOutFormatScs: Each stream 3D is exported as an SCS file.
kA3DWebOutFormatPrc: Each stream 3D is exported as a PRC file.
In client/server mode (
kA3DWebOnline), the call to the function delivers one PDF structure file (format is defined by
A3DRWParamsExportHtmlData.m_ePdfOutputFormat) and one file per 3D stream in your PDF document (format is defined by
The PDF structure file is the entry point of all. It represents your PDF document. The files will be parsed and displayed in the browser by a client web viewer that we provide as part of HOOPS Publish. See the samples directory in the package download: samples\publish\publishhtml\htmlforserver .
To help test this functionality, we have provided a simple HTTP server that can be launched by clicking on samples\publish\publishhtml\htmlforserver\exportpdftohtml\start_server.bat .
Once the server is launched, open the following URL in your browser:
localhost:11180/viewer.html?file=sample_DemoDataModel . You can load your own 3D PDF converted by updating the sample querystring parameter with the PDF structure file name describing your document without the file extension :
Be sure to properly URL-encode ‘FilenameWithoutExtension’. For instance, there are no spaces in a URL, so any space character in your file name must be replaced by “%20” (without the quotes) for a space character. See https://www.w3schools.com/tags/ref_urlencode.asp for more information about URL encoding.
By default, the viewer of a 3D annotation will display a toolbar and a panel will display the model tree and views. You can hide them by adding the following to your querystring:
&modeltree=noneto hide the panel with the model tree and views.
&toolbar=noneto hide the toolbar.
&viewNav=showto show a floating widget helping the user to navigate from one view to another.
viewer.html can load any generated file - to change the file you’re viewing, simply change the query string “file=AnotherFilenameWithoutExtension” in the URL with the new file name.
If you want to integrate this viewer into a larger website, note that the folder where viewer.html is located must be set as a root for all files in it. This will allow you to drop any set of generated files into the ‘PdfContent’ folder at any depth in the subfolders. To view an exported PDF in a subfolder of ‘PdfContent’, just change the querystring to “file=SubFolder/FilenameWithoutExtension” in the URL.
Please note, viewer.html can be customized to include your own content or logo. If you need to further customize the 3D viewer component, you might consider using HOOPS Communicator or The HOOPS Web platform. Please contact us for more information.
Integrate into an existing website
The sample contains the file viewer.html which is the entry point of our demo. The file is readable and a good starting point for those who want to integrate this solution into an existing website. The file contains a script section that checks some compatibility with web browsers, and load the PDF structure document (which is your PDF export), retrieve the content and call Hoops.PdfWebViewer.OpenDocumentFromXml(content) or Hoops.PdfWebViewer.OpenDocumentFromJson(content) where content is the content loaded as string. Beware to call the correct function in regards of the format of the PDF structure document.
HTTP Server Configuration
Use your own one like Apache HTTP, NodeJS, Python…
The configuration must enable XML/Json file transfer.
No specific port/protocol are required.
All included files are compatible with HTTPS protocol to manage security.
Also, to optimize network bandwith, it could be good to enable gzip compression for all files contained in PdfContent folder.
Single HTML File - Standalone
For single HTML standalone file output (
kA3DWebOfflineSingleFile), when calling
A3DConvertPDFToWebFormat, you should fill the
A3DRWParamsExportHtmlData data structure with new parameters. The call to the function delivers one HTML file that could be read anywhere if you havbe a compatible browser.
You must create a
A3DRWHtmlOfflineData data structure and set it with the parameter
A3DRWHtmlOfflineData.m_pHtmlOfflineData. This structure contains two additional fields :
A3DRWHtmlOfflineData.m_pcPathToHtmlViewerFileis mandatory. You must indicate the viewer file to use. This file is the entry point of our web solution and can be found in the sample directory. Please refer to previous section for how to find it.
A3DRWHtmlOfflineData.m_uiOptionFlagsis a set of options you may want to enable amongst
kA3DWebOfflineShowViewNavigation. These options are detailed in the previous section.
One of the main advantages of this mode is to enable offline viewing of the PDF. Additional benefits include, for instance, simplified cache management on mobile devices.
// This snippet is also part of the sample provided in the package A3DRWParamsExportHtmlData paramsExportData; A3D_INITIALIZE_DATA(A3DRWParamsExportHtmlData, paramsExportData); paramsExportData.m_bIncludeMeasurementInformation = A3D_TRUE; paramsExportData.m_pcHtmlTemplateName = pc3DTemplateFile; // set the output as monolithic paramsExportData.m_eHtmlOutputMode = kA3DWebOfflineSingleFile; // fill and set mandatory parameters A3DRWHtmlOfflineData offlineData; A3D_INITIALIZE_DATA(A3DRWHtmlOfflineData, offlineData); offlineData.m_pcPathToHtmlViewerFile = viewerFilePath; paramsExportData.m_pHtmlOfflineData = &offlineData; A3DStatus status = A3DConvertPDFToWebFormat(pcFileName, ¶msExportData, pcOutputDirectory, pcOutputName, kA3DWebOutFormatHtml);
Therefore, on Android, you should always have a path starting with
file:///sdcard/... Some file system explorers on Android do not open files using file protocol by default.
Single HTML File - Distributed
For this single distributed file output (
kA3DWebOfflineWithDependencies), you should also fill
A3DRWHtmlOfflineData.m_pHtmlOfflineData with the same elements.
The changes from a standalone file lie in how the file is read from the browser. This is not a standalone file as it requires js and css folders to be in the same folder as the file. Those folders are part of the sample we deliver in samples\publish\publishhtml\htmlforserver\exportpdftohtml\root.
There are two benefits for using this export :
The HTML file generated will be slightly shorter than from a standalone file as js and css files won’t be part of it.
The file will also be loaded slightly faster as jss and css files could be loaded by the browser in parallel.
However the main downside is, if you distribute this file, the one who reads it should have the js and css files on their device as well.