From 1692afeaa3d74696f91e061b828c99e518d2be7c Mon Sep 17 00:00:00 2001 From: Ioannis Filippidis Date: Sun, 15 Sep 2013 16:42:16 -0700 Subject: [PATCH] updated readme --- .gitignore | 1 + README.md | 70 ++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 53 insertions(+), 18 deletions(-) diff --git a/.gitignore b/.gitignore index e3b3e2a..eb63d09 100644 --- a/.gitignore +++ b/.gitignore @@ -85,5 +85,6 @@ syntax: glob *.mp4 # site-specific idtf2u3d/bin/* +dist/* *.u3d *.vws diff --git a/README.md b/README.md index 1c305ab..3ef7269 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,41 @@ Summary Export figure as a U3D file or directly to 3D interactive graphics within a PDF. Licensed under 2-clause BSD. -Description ------------ +[Documentation](https://www.cds.caltech.edu/~ifilippi/temp/releases/matlab/fig2u3d/fig2u3d_manual.pdf) + +[PDF created](https://www.cds.caltech.edu/~ifilippi/temp/releases/matlab/fig2u3d/example.pdf) for figure below (3d needs [Adobe Reader](http://get.adobe.com/reader/)). + + + +The `LaTeX` needed looks like: + +``` +\documentclass{article} +\usepackage{graphicx} +\usepackage[dvipdfmx]{media9} + +\begin{document} + \begin{figure} + \centering + \includemedia[ + width=0.8\textwidth, + activate=pagevisible, + %deactivate=pageinvisible, + 3Dtoolbar, + 3Dviews=./example_supercyclide.vws + ]{ + \includegraphics[width=0.8\textwidth]{example_supercyclide.pdf} + }{./example_supercyclide.u3d} + \caption{An implicitly defined elliptic supercyclide.} + \label{fig:example_supercyclide} + \end{figure} +\end{document} +``` + +## Description `fig2u3d` saves the figure as a `U3D` file for inclusion as an interactive 3-dimensional figure within a `PDF`. Either `LaTeX` or Adobe Acrobat can be used to embed the `U3D` file in the `PDF`. -The `idtf2u3d` executables are needed from [this project](http://sourceforge.net/projects/u3d/). To obtain them download [this](http://www.mathworks.com/matlabcentral/fileexchange/25383-matlab-mesh-to-pdf-with-3d-interactive-object) and place the `bin` directory in the `idtf2u3d` directory of the `fig2u3d` distribution. +The `idtf2u3d` executables are included from [this project](http://sourceforge.net/projects/u3d/) (see dependencies below). A `vws` file is also created, which contains the current camera view of the axes saved. This file can be used to set the figure's default view in the PDF to be the same with the open figure window in `MATLAB`. @@ -30,17 +60,25 @@ Graphics object supported for export include: Line colors and marker styles, surfaces and `quivers` with `NaN`s and surface shading are supported. Multiple instances of various objects can be plotted in the same axes and exported. Note that some limitations apply, for example filled contours are not yet supported. -Dependencies ------------- + -- `fig2u3d` needs the idtf2u3d converter executable by downloading [this](http://www.mathworks.com/matlabcentral/fileexchange/25383-matlab-mesh-to-pdf-with-3d-interactive-object) and placing the `bin` directory in the `idtf2u3d` directory of the `fig2u3d` distribution. +## Installation +Download & unpack from the [release](https://github.com/johnyf/fig2u3d/releases) the: + +- `MATLAB` code, +- idtf2u3d converter Mac OS X, Linux, Windows binaries, place this under `idtf2u3d/bin` (result: `idtf2u3d/bin/glx…` etc), +- required `MATLAB` packages, place them anywhere. + +Add all the above and their subdirectories to your `MATLAB` path, e.g. using the `pathtool` command. + +### Optional - `fig2pdf3d` needs a latex distribution (e.g. [MikTeX](http://miktex.org/), [TeXLive](http://www.tug.org/texlive/), [MacTeX](http://tug.org/mactex/)) and [`media9`](http://www.ctan.org/pkg/media9) (preferred) or [`movie15`](http://www.ctan.org/pkg/movie15) LaTeX package (replaced by `media9`). -Included --------- -The distribution archive includes these dependencies (not in the git repository): +## Acknowledgments +- [idtf2u3d converter](http://sourceforge.net/projects/u3d/) binaries packaging taken from [here](http://www.mathworks.com/matlabcentral/fileexchange/25383-matlab-mesh-to-pdf-with-3d-interactive-object) +### Dependencies included - [MATLAB mesh to PDF with 3d interactive object](http://www.mathworks.com/matlabcentral/fileexchange/25383-matlab-mesh-to-pdf-with-3d-interactive-object) - [Generate vertices, faces and color for U3D format](http://www.mathworks.com/matlabcentral/fileexchange/27245-generate-vertices-faces-and-color-for-u3d-format) - [Generate U3D files from STL models for making multi-layer 3D PDF figures](http://www.mathworks.com/matlabcentral/fileexchange/31413-generate-u3d-files-from-stl-models-for-making-multilayer-3d-pdf-figures) @@ -54,22 +92,18 @@ The distribution archive includes these dependencies (not in the git repository) - [Vector Norm](http://www.mathworks.com/matlabcentral/fileexchange/10708-vector-norm) - [Verbatim](http://www.mathworks.com/matlabcentral/fileexchange/23194-verbatim-get-the-text-of-a-block-comment) -Acknowledgments ---------------- +### Other - [Create 3d interactive html file from MATLAB figure](http://www.mathworks.com/matlabcentral/fileexchange/27333-create-3d-interactive-html-file-from-matlab-surface) - [MATLAB 3d figure to 3d xhtml](http://www.mathworks.com/matlabcentral/fileexchange/32207-matlab-3d-figure-to-3d-xhtml) - [Remnan](http://www.mathworks.com/matlabcentral/fileexchange/10863-remnan) - [Export Fig](http://www.mathworks.com/matlabcentral/fileexchange/23629-exportfig) -License -------- +## License This project is licensed under the 2-clause BSD license. The license file includes the authors of all dependencies, so that they can be distributed with this project. -Hosted ------- -Development on [github](https://github.com/johnyf/fig2u3d) and releases distributed also via the `MATLAB` [File Exchange](http://www.mathworks.com/matlabcentral/fileexchange/37640-export-figure-to-3d-interactive-pdf). +## Hosted +Development on [github](https://github.com/johnyf/fig2u3d), releases here and also via [File Exchange](http://www.mathworks.com/matlabcentral/fileexchange/37640-export-figure-to-3d-interactive-pdf). -Keywords --------- +## Keywords 3d, u3d, graphics, export, save, plot, surface, vector, quiver, quivergroup, mesh, contourgroup, contour, data export, mathematics, vision, latex, pdf, media9, movie15, pdflatex, xelatex