########
Overview
########

Introduction
~~~~~~~~~~~~

Advanced Publishing is a powerful SDK that enables authoring of rich engineering data and model file export to a variety of industry-standard formats, including PDF, STEP, JT, and 3MF.
The 3D data model at the core of Advanced Publishing is the ISO-certified format PRC (ISO 14739-1:2014), which provides support for engineering concepts like Assembly Tree, Topology & Geometry, Product and Manufacturing Information, and Views.


Defining a 3D Model
-------------------

There are two methods for creating 3D models in Advanced Publishing:
3D data can be authored using the Advanced Publishing API, or it can be imported from a number of native CAD file formats.

Depending on the import file format, 3D models in Advanced Publishing typically contain the following elements:
assembly trees, boundary representation, tessellation, markup (such as PMI), views, and animations.

When a CAD model is loaded into Advanced Publishing, all of the rotation, zoom, and pan controls are already in place;
this gives your end users a rich set of features for manipulating 3D models with no additional effort from your development team.

By File
~~~~~~~

3D data can be defined directly through a CAD file;
Advanced Publishing supports import via IFC, IGES, JT, SAT, STEP, XT, PRC, STL, VRML, and U3D formats.

Developers who want to embed other native CAD formats directly into a PDF (e.g., SolidWorks or CATIA files) can use HOOPS Exchange in conjunction with Advanced Publishing to perform file conversions.
For a complete list of HOOPS Exchange–supported file types, please see :doc:`/start/supported-formats`

By Direct API
~~~~~~~~~~~~~

Advanced Publishing can also be used to author a CAD model from scratch.
For instance, it can be used to create geometry, faces, parts, assembly nodes, and, finally, a model file, complete with PMI and other metadata.

The Advanced Publishing API creates 3D data using the PRC format, an open, ISO-certified file format directly supported by Adobe Acrobat.

PRC is capable of storing geometry in both precise and tessellated forms and is highly compressible, dramatically reducing file size for large 3D models.

Mixed Mode
~~~~~~~~~~

Finally, the Advanced Publishing API can be used to enrich the data coming from an imported file.
This mode is often used to add Product and Manufacturing Information (PMI) to an existing model.
It can also be used to add metadata, animations, an exploded view, or to attach a file to a Technical Data Package.

A typical use case would involve building a PRC model from an imported Parasolid or STEP file.
This model would then be traversed and enriched using our direct API, adding, for example, manufacturing data for each part in an assembly.

See ProductOccurenceEdit and RepresentationItemEdit for more information.

3D models can be exported from Advanced Publishing to the following formats:

.. _adv_pub_export_table:

.. rst-class:: format-title-block

======== =============== ========== ============== ========== ========== ================
Format   Assembly Tree   B-rep      Tessellation   PMI        View       Props Validation
======== =============== ========== ============== ========== ========== ================
3MF      |c_green|       |c_red|    |c_green|      |c_red|    |c_red|    |c_red|
HTML     |c_green|       |c_green|  |c_green|      |c_green|  |c_green|  |c_red|
IGES     |c_green|       |c_green|  |c_red|        |c_red|    |c_red|    |c_red|
JT 9.5   |c_green|       |c_green|  |c_green|      |c_green|  |c_green|  |c_red|
PDF      |c_green|       |c_green|  |c_green|      |c_green|  |c_green|  |c_red|
PRC      |c_green|       |c_green|  |c_green|      |c_green|  |c_green|  |c_green|
SCS      |c_green|       |c_green|  |c_green|      |c_green|  |c_green|  |c_red|
STEP     |c_green|       |c_green|  |c_grey|       |c_green|  |c_green|  |c_green|
STL      |c_green|       |c_red|    |c_green|      |c_red|    |c_red|    |c_red|
U3D      |c_green|       |c_red|    |c_green|      |c_red|    |c_red|    |c_red|
VRML     |c_green|       |c_red|    |c_green|      |c_red|    |c_red|    |c_red|
======== =============== ========== ============== ========== ========== ================

.. rubric:: Legend

* |c_green|   = Supported
* |c_grey|    = This concept is not supported by this format
* |c_red|     = Unsupported

.. note::

   HTML and SCS export are only available on Linux & Windows 64 bit.
   For HTML and SCS, B-rep is only available for exact measurements (and not for faceted B-rep).

Visualizing and Interrogating a 3D Model in the Browser
-------------------------------------------------------

By using Advanced Publishing to export your data into a "stream cache single" file (scs) on a web server, you can view and interrogate 3D models in a browser without the help of browser plug-ins.
On the client side, Advanced Publishing offers a JavaScript/WebGL component to display the content of an scs file directly in the browser.

.. figure:: 3d_browser.jpg
   :align: center

Advanced Publishing can also export a monolithic HTML file that embeds all the required components so that the 3D model can be viewed in a browser even without a connection to a web server.

Creating Rich PDF Documents
---------------------------

In addition to encapsulating a 3D model in a context that can be manipulated via pan, zoom, and rotation, Advanced Publishing can be used to create rich documents.
After all, PDF offers more than 3D visualization and manipulation – it's also a container for engineering data that might be used for documents such as RFPs or Engineering Releases.

With Advanced Publishing, developers can insert 3D, pictures, text, tables, and attach files (e.g., a Word doc or an Excel spreadsheet).

Creating Your PDF Document
~~~~~~~~~~~~~~~~~~~~~~~~~~

Because Advanced Publishing is based on native Adobe technology, it can open any existing PDF file.
These PDFs can be merged, enriched, or used as a template.
It's also possible to create a PDF file from scratch.

Any existing PDF file can be used as a template, and if you're already generating PDF files in your application, you can enrich these PDFs with Advanced Publishing, replacing, for instance, simple 3D-on-a-page with an interactive 3D model that users can rotate, pan, and zoom.

The Advanced Publishing API can retrieve any field inside a 3D PDF, such as field names and field positions, and then modify them.
For instance, it can insert text into a text box, or change the icon of a button.

.. note::

   To enable testing of PDF/A-4e file creation using Advanced Publishing, we are introducing a new Experimental API :c:func:`A3DPDFDocumentSaveToPDFA4e`.
   This API is currently in an experimental state due to the limited adoption of PDF 2.0 and our ongoing evaluation of its supported and unsupported features. 
   Because of the restrictions imposed by PDF 2.0 and the PDF/A-4e standard, some data loss may occur compared to PDF files generated with Advanced Publishing API :c:func:`A3DPDFDocumentSaveEx`.
   Importantly, generating a PDF 2.0 (PDF/A-4e) document is provided as an additional option and does not replace the default PDF 1.7 output that HOOPS Exchange continues to support.
   PDF 2.0 (PDF/A-4e) has been specifically designed for the long-term archiving of engineering documents, making this a valuable opportunity for Exchange users who publish PDF files to explore the new format. 
   We encourage you to test the API and share feedback on any critical gaps or missing features that should be addressed.
   Tech Soft 3D remains committed to supporting all features compliant with the PDF 2.0 / PDF/A-4e standard. For further details on the PDF/A-4e standard, please refer to https://www.loc.gov/preservation/digital/formats/fdd/fdd000318.shtml.


Handling Security, Attachments, and File Compression
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

With Advanced Publishing, developers can leverage Acrobat's standard security tools, offering users a familiar interface for unlocking password-secured PDFs or adding digital signatures.

The generated PDF document uses the standard file-wide compression that Adobe implements via the PDF Library SDK.
Additionally, the PRC file format includes advanced compression to significantly reduce the size of the 3D data, often 20 to 100 times smaller than a native CAD file.

Lastly, it's possible to attach files to the PDF document.
This feature is used, for example, by developers who wish to include the original CAD data in the PDF document.

Adding Interactivity to Your PDF
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Interactive PDFs are frequently used for work instruction documents, training materials, or reports with interactive charts and graphs.

These PDFs typically make use of simple widgets like buttons, check boxes, list boxes, drop-downs, filters, or more advanced customized widgets like view carousels or sliding tables.
By clicking one of these widgets or by selecting data in the 3D model, users can change the information displayed and replicate behavior of a native application or web page.
This dynamic interface makes it possible to consolidate into a single page all of the information that would traditionally span dozens of PDF pages, while at the same time reducing the risk of errors often introduced during the document production process.

.. figure:: LG_PDF.png
   :align: center

JavaScript
----------

Advanced Publishing takes full advantage of Adobe's built-in JavaScript for Acrobat 3D Annotations API to define a virtually unlimited set of interactions between the end user, the 3D model, and the PDF document.

Advanced Publishing will automatically generate the JavaScript for common interactions.
However, if developers want to author their own JavaScript they can do that, too.

Using the Advanced Publishing API, it's simple to inject JavaScript into your PDF, which can, for example, create views and 2D model images, define actions on a particular field, play an animation, navigate a view carousel, or populate list boxes.

Data Model
----------

If you've defined a rich 3D model, Advanced Publishing can auto-generate PDF objects (such as a parts list or view carousel) to interact with the model.

These interactions are defined programmatically using the C++ API.

Tetra 4D Enrich
---------------

PDF templates generated using the Tetra 4D Enrich Acrobat plugin are a simple and easy way to add interactivity to your documents.

Tetra 4D Enrich templates support advanced functionality such as view carousels, but require no extra coding from your development team.

Next Steps
~~~~~~~~~~

As a full-featured SDK built on top of Adobe Acrobat's native 3D technology, Advanced Publishing offers a workflow to meet just about every need.
To help familiarize yourself with the available functionality, the :ref:`sample_import_publish` example code is a good place to start.


