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 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.
Next we tell the Rich Media Annotation when to activate and when to deactivate. Three option for each are defined in the PDF specification.
- The content is clicked
- The page containing the content is opened
- The page containing the content is visible
- “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.
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.
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.
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.