Creating 3D PDF files using the Datalogics PDF Java Toolkit

Creating 3D PDF files using the Datalogics PDF Java Toolkit

Sample of the Week:

This Gist is not going to be for the faint of heart. You’re going to want to have a copy of the PDF Specification handy paying particular attention to section 13.6 “3D Artwork”. Actually inserting the 3D model isn’t really all this complicated and we do it in the first few lines of code…

… the rest of the sample reproduces the rest of the functionality performed by the “Insert 3D” dialog in Acrobat. Acrobat is capable not only of inserting the 3D model, it can create previews for PDF viewers that don’t support 3D, it can add JavaScripts that run when the 3D model instantiates, set the lighting style, set the startup options for the annotation, it can read existing views from the model, and create additional views. In short, this sample not only inserts the 3D model, it creates a fully functional 3D Annotation in the same way as Adobe Acrobat… with all the bells and whistles. So… it’s a bit complicated.

The other issue is, in order to create some interesting views of the 3D model, you need to understand the model in question. Views are really just camera positions and to position the camera correctly, you need to understand what you’re looking at. For example, you won’t see much if the camera is initially positioned inside a solid part; you’d just see the inside edges of the part.

Note: This sample leaves the step of interpreting the model and discover the proper camera matrices as an exercise for the developer. This means that the numbers in the matrices used in the sample are specific to the model being used as the input file. If you are adapting the code to your own needs, you’ll need to replace the matrices with ones that match your model. You’ll want to integrate a U3D or PRC library or some other mechanism to get them but the mechanics of what to do with the matrices once you have them is, in fact, present in the sample.

So if I haven’t scared you too badly, let’s get started. As you can see in the snippet above, it’s relatively simple to insert the 3D model into a PDF page inside a Rich Media Annotation. To add a JavaScript that executes when the viewer creates an instance of the 3D model, you follow pretty much the same process, the only difference is the last step when you assign the JavaScript stream to the OnInstantiate property. The JavaScript in this sample will start and repeat the animation to assemble and disassemble the model.

Next we tell the Rich Media Annotation when to activate and when to deactivate. Three option for each are defined in the PDF specification.

Activation when…

  • The content is clicked
  • The page containing the content is opened
  • The page containing the content is visible

Deactivate when…

  • “Disable Content” is selected from the context menu
  • The page containing the content is closed
  • The page containing the content is not visible  

I’ve set all six options up as constants on the sample because their ASNames are essentially meaningless. But once you have the ASName, creating and setting the Activation dictionary is very straightforward.

Next we set up the 3D view dictionary for the default view. The settings below mimic what Adobe Acrobat does when importing a U3D model that has no default lighting scheme. It also adds the default background color that Acrobat would add. Like with Acrobat, this view will NOT appear in the list of model views and cannot be addressed via JavaScript. Start by creating the default view and add it to the annotation. This Object corresponds to the 3DV dictionary. See table 298 of the PDF Specification. Next create and add the lighting scheme dictionary to the view. See table 304 of the PDF Specification. Then create and add the background color to the view.

Now we want to create and add an Appearance or “Poster” to the 3D Annotation. This is what displays when the annotation is not active or when the file is being displayed in a viewer that can’t show 3D. Normally, you’d use a U3D or PRC parser to create an image but for the purposes of this sample, I’ve done that for you and the image is included in the input files. If you’ve looked at any of the Stamp Annotation samples for the Java Toolkit, this will look familiar.

Then we use similar code to read in an image that the JavaScript will set as the background image of the 3D Annotation. Images and other files that are added with this technique can be addressed by the 3D JavaScript Interpreter by URLs that begin with “pdf://”.

At this point, you’ve got a mostly functional 3D PDF but this is as far as you can go without knowing more about the U3D geometry of your specific model. If you are unfamiliar with how to work with 3D models or don’t have access to a U3D tool set… stop… back away slowly… and don’t make any sudden movements… otherwise, keep reading.

In order to make the “Home” button in the 3D toolbar function properly in the viewer, you need add camera settings specific to the model in question. Specifically, you’ll need a 12-element 3D transformation matrix that specifies the position and orientation of the camera in world coordinates. It’s actually a 4×4 matrix but only the first three columns of the matrix change; so the matrix is expressed in PDF as an array of 12 numbers. See “Section 13.6.5 Coordinate Systems for 3D” in the PDF Specification for further details.  Normally, you’d get this information by using a U3D parser and doing a lot of math. But for the purposes of this sample, I’ve already done that for you. These numbers are specific to the input U3D supplied above. Don’t expect them to work for any other models.

With these additional settings added to the default view, the “Home” button on the 3D toolbar will now be functional but we can also add additional views. The following section will add the equivalent of the Acrobat generated default views for Left, Top, Front, Right, Bottom, and Back. However, the first thing we are going to do is make the Default view available to the JavaScript for Acrobat 3D Annotations API by creating a view array and adding the default view to it. This is also where we’ll add the additional views. First we need to set it’s external name; this is the name that appears in the list of views. Because in Acrobat the default view is represented on the 3D toolbar, I’m using the name “Home” for the default view. However, this view will be addressed by JavaScript using it’s internal name “default” as we set above.

If you are using a PRC model, simply replace the “PDF3DDStream.k_U3D” constant in line 98 with “PDF3DDStream.k_PRC”. All the other code is the same.

To get started with 3D PDF files, download this Gist and request an evaluation copy of The Datalogics PDF Java Toolkit.

Leave a Reply

Your email address will not be published. Required fields are marked *