Structural Bioinformatics Library
Template C++ / Python API for developping structural bioinformatics applications.
User Manual

Alpha_complexes_extensions

Authors: F. Cazals and T. Dreyfus

Introduction

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

  • visualizing a 3D weighted $\alpha$-complex using molecular viewers,
  • serializing a 3D weighted $\alpha$-complex.

These functionality are provided for the 3D weighted $\alpha$-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 $\alpha$-complex, except the tetrahedra. The package Molecular_viewers works as follows :

  • (i) open a file,
  • (iii) output the 3D weighted $\alpha$-complex using the output stream operator on the viewer.

There are two ways to output a 3D weighted $\alpha$-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 $\alpha$-complex.
  • by dumping directly the $\alpha$-complex; it will output only the edges and faces of the underlying triangulation that are in the $\alpha$-complex.

See Visualization with VMD for an example.

Serialization

It uses the Boost serialization library for serializing the vertices of the $\alpha$-complex. More precisely, each vertex of the $\alpha$-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 $\alpha$-complex of the input, and save in a visualization state file for VMD the vertices, edges and faces of the $\alpha$-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_euclidean_traits_3.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::Regular_triangulation_euclidean_traits_3<K> RTraits;
typedef CGAL::Alpha_shape_cell_base_3<RTraits, CGAL::Regular_triangulation_cell_base_3<RTraits> > Cb;
typedef CGAL::Alpha_shape_vertex_base_3<RTraits> Vb;
typedef CGAL::Triangulation_data_structure_3<Vb, Cb> Tds;
typedef CGAL::Regular_triangulation_3<RTraits, Tds> Regular_triangulation_3;
typedef CGAL::Alpha_shape_3<Regular_triangulation_3> Alpha_complex_3;
int main(int argc, char *argv[])
{
std::ifstream in(argv[1]);
if(!in.is_open()) return -1;
std::vector<CGAL::Weighted_point<K::Point_3, K::FT> > weighted_points;
while(!in.eof())
{
double x, y, z, r;
in >> x >> y >> z >> r;
if(in.eof())
continue;
weighted_points.push_back(CGAL::Weighted_point<K::Point_3, K::FT>(K::Point_3(x, y, z), r*r));
}
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;
return 0;
}

Serializing the vertices

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

#include <iostream>
#include <fstream>
#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
#include <CGAL/Regular_triangulation_euclidean_traits_3.h>
#include <CGAL/Regular_triangulation_3.h>
#include <CGAL/Alpha_shape_3.h>
#include <SBL/IO/Alpha_complex_3_serialize.hpp>
#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::Regular_triangulation_euclidean_traits_3<K> RTraits;
typedef CGAL::Alpha_shape_cell_base_3<RTraits, CGAL::Regular_triangulation_cell_base_3<RTraits> > Cb;
typedef CGAL::Alpha_shape_vertex_base_3<RTraits> Vb;
typedef CGAL::Triangulation_data_structure_3<Vb, Cb> Tds;
typedef CGAL::Regular_triangulation_3<RTraits, Tds> Regular_triangulation_3;
typedef CGAL::Alpha_shape_3<Regular_triangulation_3> Alpha_complex_3;
int main(int argc, char *argv[])
{
std::ifstream in(argv[1]);
if(!in.is_open()) return -1;
std::vector<CGAL::Weighted_point<K::Point_3, K::FT> > weighted_points;
while(!in.eof())
{
double x, y, z, r;
in >> x >> y >> z >> r;
if(in.eof())
continue;
weighted_points.push_back(CGAL::Weighted_point<K::Point_3, K::FT>(K::Point_3(x, y, z), r*r));
}
in.close();
Alpha_complex_3 A(weighted_points.begin(), weighted_points.end());
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;
}