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.
PDF Features
No plugin required
Our technology is written in native HTML/CSS and JavaScript.
It implements a subset of Acrobat JavaScript API as described in Acrobat 11 SDK.
Support 3D PDF interactivity
Other Hoops Publish features such as BOM Tables, Carousels are fully supported.
Most common actions from Adobe Acrobat are supported such as “Open a web link”, “open a file”, “Go to 3D View”, “Run a JavaScript”…
Browser compatibility
The generated document can be viewed using:
Google Chrome 69+
Safari 11.1+
Firefox 60+
More specifically, your browser must be able to support: - JS ECMA class definition and inheritance - strict mode - JavaScript proxy feature (get/set)
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 A3DConvertPDFToWebFormat()
.
// 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);
The file 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.
Client/Server Integration
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 A3DRWParamsExportHtmlData.m_i3dOutputFormat
).
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 : localhost:11180/viewer.html?file=FilenameWithoutExtension
.
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=none
to hide the panel with the model tree and views.&toolbar=none
to hide the toolbar.&viewNav=show
to show a floating widget helping the user to navigate from one view to another.
Example: localhost:11180/viewer.html?file=sample_DemoDataModel&modeltree=none&toolbar=none
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 sub-folders. To view an exported PDF in a sub-folder 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 bandwidth, 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 have 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_pcPathToHtmlViewerFile
is 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_uiOptionFlags
is a set of options you may want to enable amongstkA3DWebOfflineShow3DToolbar
,kA3DWebOfflineShow3DModelView
andkA3DWebOfflineShowViewNavigation
. 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);
Android specificities
On Android, the browsers have different security settings. Chrome, for instance, blocks the linking of JavaScript files if the HTML is opened using something else than the file protocol.
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 JS 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.