Added license

Author: rjc8237

README.md

@@ -17,7 +17,7 @@ This method generates an approximately isometric parameterization of an input `o
 To install this project on a Unix-based system, use the following standard CMake build procedure:
 
 ```bash
-git clone https://github.com/rjc8237/penner-optimization.git
+git clone https://github.com/geometryprocessing/penner-optimization.git
 cd penner-optimization
 mkdir build
 cd build
@@ -27,7 +27,6 @@ make -j 4
 
 ## Usage
 
-TODO Make binary folder
 The core parameterization method is `bin/optimize_metric`. This executable takes the following arguments:
 
 |flag | description|
@@ -38,21 +37,21 @@ The core parameterization method is `bin/optimize_metric`. This executable takes
 |`direction` | Direction to use for descent|
 |`--num_iter` | Maximum number of iterations|
 |`--output` | Output directory|
+|`--show_parameterization` | Open polyscope viewer for the output|
 
 Supported parameter values for `energy` and `direction` are listed by `bin/optimize_metric --help`.
 
-The input mesh must be a manifold surface with a single connected component. The cone file must be a list of newline separated target vertex cone angles satisfying the discrete Gauss-Bonnet condition. Such a cone prescription can be generated by TODO. The output is a refined mesh with a parameterization and a file of metric coordinate values.
+The input mesh must be a manifold surface with a single connected component. The cone file must be a list of newline separated target vertex cone angles satisfying the discrete Gauss-Bonnet condition. Methods to generate such a cone prescription will be provided soon. The output is a refined mesh with a parameterization and a file of metric coordinate values.
 
-We also provide the executable `bin/optimize_shear` for generating parameterizations using explicit shear coordinate optimization (see paper for details). The executable arguments and output are the same, but the allowed directions are different.
+We also provide the executable `bin/optimize_shear` for generating parameterizations using explicit shear coordinate optimization (see paper for details). The executable arguments and output are the same, but the allowed directions are different. This method is in practice much slower to converge than the metric optimization method, but it does have standard formal convergence guarantees.
 
 ## Figure Reproduction
 
 Scripts to generate the figures of "Metric Optimization in Penner Coordinates" are included in `figures`.
 
 ![Some example figures](media/examples.jpg)
 
-TODO
-The models (with parameterizations) and cameras used in [Algebraic Smooth Occluding Contours](http://ryanjcapouellez.com/papers/algebraic_smooth_occluding_contours.html) necessary for these scripts can be downloaded [here](http://ryanjcapouellez.com/papers/algebraic-contours-data.zip); they must be copied to `data/meshes` and `data/cameras` respectively.
+The models (with cone angles) and cameras used in [Metric Optimization in Penner Coordinates](https://dl.acm.org/doi/10.1145/3618394) necessary for these scripts can be downloaded [here](https://cims.nyu.edu/gcl/papers/2021-Conformal.zip);  `MPZ_closed`, `MPZ_open`, `MPZ_cut`, and `cameras` must be copied to `data/closed-Myles`, `data/open-Myles`, `data/cut-Myles`, and `data/cameras` respectively.
 
 A Conda environment must be activated (before compiling the code) with
 ```
@@ -64,23 +63,23 @@ The figure bash scripts can then be run independently or in batch with
 bash fig-all.sh
 ```
 
-Note that most bash scripts generate an output directory with a JSON file specifying parameters for the parameterization and rendering pipeline python script `scripts/pipeline.py`. Such JSON files can also be used for general batch parameterization and analysis.
+Note that most bash scripts generate an output directory with a JSON file specifying parameters for the parameterization and rendering pipeline python script `scripts/_pipeline.py`. Such JSON files can also be used for general batch parameterization and analysis.
 
 ### Library
 
 Many parametrization and mapping-related problems in geometry processing can be viewed as metric optimization problems, i.e., computing a metric minimizing a functional and satisfying a set of constraints, such as flatness.
 
 Penner coordinates are global coordinates on the space of metrics on meshes with a fixed vertex set and topology, but varying connectivity, making it homeomorphic to the Euclidean space of dimension equal to the number of edges in the mesh, without any additional constraints imposed.
 
-Crucially for practical applications, a new mesh with standard Euclidean edge lengths corresponding to a metric determined by arbitrary Penner coordinates can be computed by an efficient algorithm. Moreover, the new mesh only differs from the original by a finite sequence of edge flips. Since the resulting edge lengths are analytic functions of the Penner coordinates, standard first-order optimization methods can be applied.
+Crucially for practical applications, there is an efficient algorithm to convert these abstract Penner coordinates to a more familiar representation of a metric: a mesh with standard Euclidean logarithmic edge lengths. Moreover, this mesh only differs from the input mesh by a finite sequence of edge flips, and the resulting edge lengths are analytic functions of the Penner coordinates. We can thus formulate many constraints, such as vertex cone angles, on the mesh with Euclidean edge lengths as differentiable functions of Penner coordinates.
 
 To engender future work in this exciting direction, we provide a library `PennerOptimizationLib` containing:
 
 1. A representation of a mesh with Penner coordinates and cone angle constraints that supports:
-   1.  the computation of the corresponding mesh with Euclidean log edge lengths and the Jacobian of the log edge lengths with respect to Penner coordinates
+   1.  the computation of the corresponding mesh with Euclidean logarithmic edge lengths and the Jacobian of the logarithmic edge lengths with respect to Penner coordinates
    2.  conformal projection to the cone angle constraints
 2.  Various energy functionals and constrained optimization methods for meshes with Penner coordinates
-3.  Layout and refinement methods to generate a parameterization for a mesh with arbitrary Penner coordinates such that the parameterization has the intrinsic metric prescribed by the coordinates.
+3.  Layout and refinement methods to generate a parameterization for a mesh from arbitrary Penner coordinates, i.e., the parameterization is an embedding in the uv plane of the metric defined by the Penner coordinate.
 
 ## Citation
 

src/app/optimize_metric.cpp

@@ -1,3 +1,33 @@
+/*********************************************************************************
+*  This file is part of reference implementation of SIGGRAPH Asia 2023 Paper     *
+*  `Metric Optimization in Penner Coordinates`           *
+*  v1.0                                                                          *
+*                                                                                *
+*  The MIT License                                                               *
+*                                                                                *
+*  Permission is hereby granted, free of charge, to any person obtaining a       *
+*  copy of this software and associated documentation files (the "Software"),    *
+*  to deal in the Software without restriction, including without limitation     *
+*  the rights to use, copy, modify, merge, publish, distribute, sublicense,      *
+*  and/or sell copies of the Software, and to permit persons to whom the         *
+*  Software is furnished to do so, subject to the following conditions:          *
+*                                                                                *
+*  The above copyright notice and this permission notice shall be included in    *
+*  all copies or substantial portions of the Software.                           *
+*                                                                                *
+*  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR    *
+*  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,      *
+*  FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE  *
+*  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER        *
+*  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING       *
+*  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS  *
+*  IN THE SOFTWARE.                                                              *
+*                                                                                *
+*  Author(s):                                                                    *
+*  Ryan Capouellez, Denis Zorin,                                                 *
+*  Courant Institute of Mathematical Sciences, New York University, USA          *
+*                                          *                                     *
+*********************************************************************************/
 #include <igl/readOBJ.h>
 #include <igl/writeOBJ.h>
 #include "common.hh"

src/app/optimize_shear.cpp

@@ -1,3 +1,33 @@
+/*********************************************************************************
+*  This file is part of reference implementation of SIGGRAPH Asia 2023 Paper     *
+*  `Metric Optimization in Penner Coordinates`           *
+*  v1.0                                                                          *
+*                                                                                *
+*  The MIT License                                                               *
+*                                                                                *
+*  Permission is hereby granted, free of charge, to any person obtaining a       *
+*  copy of this software and associated documentation files (the "Software"),    *
+*  to deal in the Software without restriction, including without limitation     *
+*  the rights to use, copy, modify, merge, publish, distribute, sublicense,      *
+*  and/or sell copies of the Software, and to permit persons to whom the         *
+*  Software is furnished to do so, subject to the following conditions:          *
+*                                                                                *
+*  The above copyright notice and this permission notice shall be included in    *
+*  all copies or substantial portions of the Software.                           *
+*                                                                                *
+*  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR    *
+*  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,      *
+*  FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE  *
+*  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER        *
+*  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING       *
+*  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS  *
+*  IN THE SOFTWARE.                                                              *
+*                                                                                *
+*  Author(s):                                                                    *
+*  Ryan Capouellez, Denis Zorin,                                                 *
+*  Courant Institute of Mathematical Sciences, New York University, USA          *
+*                                          *                                     *
+*********************************************************************************/
 #include <igl/readOBJ.h>
 #include <igl/writeOBJ.h>
 #include "common.hh"

src/app/plot_shear_energy.cpp

@@ -1,3 +1,33 @@
+/*********************************************************************************
+*  This file is part of reference implementation of SIGGRAPH Asia 2023 Paper     *
+*  `Metric Optimization in Penner Coordinates`           *
+*  v1.0                                                                          *
+*                                                                                *
+*  The MIT License                                                               *
+*                                                                                *
+*  Permission is hereby granted, free of charge, to any person obtaining a       *
+*  copy of this software and associated documentation files (the "Software"),    *
+*  to deal in the Software without restriction, including without limitation     *
+*  the rights to use, copy, modify, merge, publish, distribute, sublicense,      *
+*  and/or sell copies of the Software, and to permit persons to whom the         *
+*  Software is furnished to do so, subject to the following conditions:          *
+*                                                                                *
+*  The above copyright notice and this permission notice shall be included in    *
+*  all copies or substantial portions of the Software.                           *
+*                                                                                *
+*  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR    *
+*  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,      *
+*  FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE  *
+*  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER        *
+*  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING       *
+*  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS  *
+*  IN THE SOFTWARE.                                                              *
+*                                                                                *
+*  Author(s):                                                                    *
+*  Ryan Capouellez, Denis Zorin,                                                 *
+*  Courant Institute of Mathematical Sciences, New York University, USA          *
+*                                          *                                     *
+*********************************************************************************/
 #include "common.hh"
 #include "explicit_optimization.hh"
 #include "energies.hh"

src/core/area.cpp

@@ -1,3 +1,33 @@
+/*********************************************************************************
+*  This file is part of reference implementation of SIGGRAPH Asia 2023 Paper     *
+*  `Metric Optimization in Penner Coordinates`           *
+*  v1.0                                                                          *
+*                                                                                *
+*  The MIT License                                                               *
+*                                                                                *
+*  Permission is hereby granted, free of charge, to any person obtaining a       *
+*  copy of this software and associated documentation files (the "Software"),    *
+*  to deal in the Software without restriction, including without limitation     *
+*  the rights to use, copy, modify, merge, publish, distribute, sublicense,      *
+*  and/or sell copies of the Software, and to permit persons to whom the         *
+*  Software is furnished to do so, subject to the following conditions:          *
+*                                                                                *
+*  The above copyright notice and this permission notice shall be included in    *
+*  all copies or substantial portions of the Software.                           *
+*                                                                                *
+*  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR    *
+*  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,      *
+*  FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE  *
+*  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER        *
+*  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING       *
+*  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS  *
+*  IN THE SOFTWARE.                                                              *
+*                                                                                *
+*  Author(s):                                                                    *
+*  Ryan Capouellez, Denis Zorin,                                                 *
+*  Courant Institute of Mathematical Sciences, New York University, USA          *
+*                                          *                                     *
+*********************************************************************************/
 #include "area.hh"
 
 #include "embedding.hh"

src/core/area.hh

@@ -1,3 +1,33 @@
+/*********************************************************************************
+*  This file is part of reference implementation of SIGGRAPH Asia 2023 Paper     *
+*  `Metric Optimization in Penner Coordinates`           *
+*  v1.0                                                                          *
+*                                                                                *
+*  The MIT License                                                               *
+*                                                                                *
+*  Permission is hereby granted, free of charge, to any person obtaining a       *
+*  copy of this software and associated documentation files (the "Software"),    *
+*  to deal in the Software without restriction, including without limitation     *
+*  the rights to use, copy, modify, merge, publish, distribute, sublicense,      *
+*  and/or sell copies of the Software, and to permit persons to whom the         *
+*  Software is furnished to do so, subject to the following conditions:          *
+*                                                                                *
+*  The above copyright notice and this permission notice shall be included in    *
+*  all copies or substantial portions of the Software.                           *
+*                                                                                *
+*  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR    *
+*  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,      *
+*  FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE  *
+*  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER        *
+*  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING       *
+*  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS  *
+*  IN THE SOFTWARE.                                                              *
+*                                                                                *
+*  Author(s):                                                                    *
+*  Ryan Capouellez, Denis Zorin,                                                 *
+*  Courant Institute of Mathematical Sciences, New York University, USA          *
+*                                          *                                     *
+*********************************************************************************/
 #pragma once
 
 #include "common.hh"