User Manual

Alpha_complexes_extensions

Authors: F. Cazals and T. Dreyfus

Introduction

The 3D weighted -complex is intensively used in the SBL library for modeling molecules. This package provides two major tools for:

• visualizing a 3D weighted -complex using molecular viewers,

• serializing a 3D weighted -complex.

These functionality are provided for the 3D weighted -complex data structures of the CGAL library, namely CGAL::Alpha_shape_3 and CGAL::Fixed_alpha_shape_3.

Functionality

Visualization

It uses the package Molecular_viewers for creating input files of molecular viewers such as PyMOL or VMD for visualizing the simplices of a 3D weighted -complex, except the tetrahedra. The package Molecular_viewers works as follows :

• (i) open a file,

• (ii) create the viewer (e.g SBL::IO::VMD_viewer) on the open file

• (iii) output the 3D weighted -complex using the output stream operator on the viewer.

There are two ways to output a 3D weighted -complex:

• by iterating over each simplex, and dumping each simplex; it will output all simplices of the underlying triangulation whatever is the status of the simplex in the -complex.

• by dumping directly the -complex; it will output only the edges and faces of the underlying triangulation that are in the -complex.

See Visualization with VMD for an example.

Serialization

It uses the Boost serialization library for serializing the vertices of the -complex. More precisely, each vertex of the -complex can be serialized exactly as the vertex of the underlying triangulation, as defined in the package Triangulations_extensions_3.

See Serializing the vertices for an example.

Examples

Visualization with VMD

The following example load a plain text file of 3D spheres, compute the -complex of the input, and save in a visualization state file for VMD the vertices, edges and faces of the -complex. Note that the vertices are represented as 3D transparent red spheres, while the other simplices are represented with opaque red geometric objects.

#include <iostream>
#include <fstream>
 
#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
#include <CGAL/Regular_triangulation_3.h>
#include <CGAL/Alpha_shape_3.h>
 
#include <SBL/IO/VMD_viewer.hpp>
#include <SBL/IO/Alpha_complex_3_molecular_view.hpp>
 
//Instantiation of the 3D weighted alpha-complex with CGAL, using rational number types.
typedef CGAL::Exact_predicates_inexact_constructions_kernel K;
typedef CGAL::Alpha_shape_cell_base_3<K, CGAL::Regular_triangulation_cell_base_3<K> > Cb;
typedef CGAL::Alpha_shape_vertex_base_3<K, CGAL::Regular_triangulation_vertex_base_3<K>> Vb;
typedef CGAL::Triangulation_data_structure_3<Vb, Cb> Tds;
typedef CGAL::Regular_triangulation_3<K, Tds> Regular_triangulation_3;
typedef CGAL::Alpha_shape_3<Regular_triangulation_3> Alpha_complex_3;
 
int main(int argc, char *argv[])
{
  if(argc < 2 || argc > 3) {
    return -1;
  }
 
  std::ifstream in(argv[1]);
 
  if (!in.is_open()) {
    return -1;
  }
 
  std::vector<CGAL::Weighted_point_3<K> > weighted_points;
  while (!in.eof()) {
    CGAL::Weighted_point_3<K> wp;
    in >> wp;
    if (in.eof()) {
      continue;
    }
    weighted_points.push_back(wp);
  }
  in.close();
 
  K::FT alpha = 0;
  if (argc > 2) {
    alpha = atof(argv[2]);
  }
 
  Alpha_complex_3 A(weighted_points.begin(), weighted_points.end(), alpha);
  //by default, it retains only the regular components
  A.set_mode(Alpha_complex_3::GENERAL);
 
  std::ofstream out("alpha_complex_3.vmd");
  SBL::IO::VMD_viewer viewer(out);
 
  viewer.make_new_molecule("Balls");
  viewer.set_graphics_transparent(true);
  viewer.set_graphics_color("blue");
  viewer << std::make_pair(A.finite_vertices_begin(), A.finite_vertices_end());
  viewer.make_new_molecule("Alpha-complex");
  viewer.set_graphics_transparent(false);
  viewer.set_graphics_color("red");
  viewer << &A;
  viewer.set_graphics_transparent(true);
  viewer.set_graphics_color("green");
  for (Alpha_complex_3::Finite_edges_iterator it = A.finite_edges_begin(); it != A.finite_edges_end(); ++it) {
    if (A.classify(*it) != Alpha_complex_3::EXTERIOR) {
      viewer << std::make_pair((const Alpha_complex_3*)&A, *it);
    }
  }
  for(Alpha_complex_3::Finite_facets_iterator it = A.finite_facets_begin(); it != A.finite_facets_end(); it++) {
    if(A.classify(*it) != Alpha_complex_3::EXTERIOR) {
      viewer << std::make_pair((const Alpha_complex_3*)&A, *it);
    }
  }
 
  return 0;
}

Serializing the vertices

The following example load a plain text file of 3D spheres, compute the -complex of the input, and save in an archive the vertices of the output -complex.

#include <iostream>
#include <fstream>
 
#include <SBL/IO/VMD_viewer.hpp>
#include <SBL/IO/Alpha_complex_3_serialize.hpp>
 
#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
#include <CGAL/Regular_triangulation_3.h>
#include <CGAL/Alpha_shape_3.h>
 
#include <boost/archive/xml_oarchive.hpp>
#include <boost/serialization/list.hpp>
 
//Instantiation of the 3D weighted alpha-complex with CGAL, using rational number types.
typedef CGAL::Exact_predicates_inexact_constructions_kernel K;
typedef CGAL::Alpha_shape_cell_base_3<K, CGAL::Regular_triangulation_cell_base_3<K> > Cb;
typedef CGAL::Alpha_shape_vertex_base_3<K, CGAL::Regular_triangulation_vertex_base_3<K>> Vb;
typedef CGAL::Triangulation_data_structure_3<Vb, Cb> Tds;
typedef CGAL::Regular_triangulation_3<K, Tds> Regular_triangulation_3;
typedef CGAL::Alpha_shape_3<Regular_triangulation_3> Alpha_complex_3;
 
int main(int argc, char *argv[])
{
  if(argc < 2 || argc > 3) {
    return -1;
  }
 
  std::ifstream in(argv[1]);
 
  if (!in.is_open()) {
    return -1;
  }
 
  std::vector<CGAL::Weighted_point_3<K>> weighted_points;
  while(!in.eof()) {
    CGAL::Weighted_point_3<K> wp;
    in >> wp;
    if(in.eof()) {
      continue;
    }
    weighted_points.push_back(wp);
  }
  in.close();
 
  K::FT alpha = 0;
  if (argc > 2) {
    alpha = atof(argv[2]);
  }
 
  Alpha_complex_3 A(weighted_points.begin(), weighted_points.end(), alpha);
 
  std::ofstream out("alpha_complex_3.xml");
  boost::archive::xml_oarchive* ar = new boost::archive::xml_oarchive(out);
  std::list<Alpha_complex_3::Vertex> vertices(A.finite_vertices_begin(), A.finite_vertices_end());
  *ar << boost::serialization::make_nvp("alpha-complex", vertices);
  delete ar;
  out.close();
 
  return 0;
}