Visualization in Polyhedral Geometry: Allow options and multiple obje…

…cts (#3569)

- Add visualization for SimplicialComplex
- Allow composition
- Allow many options for visualizaion

---------

Co-authored-by: Lars Kastner <lars.kastner@posteo.de>

docs/src/PolyhedralGeometry/intro.md

@@ -177,7 +177,7 @@ fan for its construction, see [`polyhedral_fan`](@ref).
 Lower dimensional polyhedral objects can be visualized through polymake's backend.
 
 ```@docs
-visualize(P::Union{Polyhedron{T}, Cone{T}, PolyhedralFan{T}, PolyhedralComplex{T}}) where T<:Union{QQFieldElem, Float64, EmbeddedNumFieldElem}
+visualize(P::Union{Polyhedron{<:Union{Float64,FieldElem}}, Cone{<:Union{Float64,FieldElem}}, PolyhedralFan{<:Union{Float64,FieldElem}}, PolyhedralComplex{<:Union{Float64,FieldElem}}, SubdivisionOfPoints{<:Union{Float64,FieldElem}}, Graph, SimplicialComplex}; kwargs...)
 ```
 
 

src/Oscar.jl

@@ -246,6 +246,9 @@ include("Combinatorics/OrderedMultiIndex.jl")
 include("Combinatorics/Matroids/JMatroids.jl")
 include("Combinatorics/Compositions.jl")
 include("Combinatorics/EnumerativeCombinatorics/EnumerativeCombinatorics.jl")
+
+include("PolyhedralGeometry/visualization.jl") # needs SimplicialComplex
+
 include("Combinatorics/PhylogeneticTrees.jl")
 
 include("StraightLinePrograms/StraightLinePrograms.jl")

src/PolyhedralGeometry/PolyhedralGeometry.jl

@@ -22,7 +22,6 @@ include("mixed_integer_linear_program.jl")
 include("LP_file_format.jl")
 include("groups.jl")
 include("type_functions.jl")
-include("visualization.jl")
 include("solving_integrally.jl")
 include("triangulations.jl")
 

src/PolyhedralGeometry/visualization.jl

@@ -1,15 +1,104 @@
+const visual_supported_types = Union{PolyhedralObjectUnion,Graph,SimplicialComplex}
+
 @doc raw"""
-    visualize(P::Union{Polyhedron{T}, Cone{T}, PolyhedralFan{T}, PolyhedralComplex{T}, SubdivisionOfPoints{T}}) where T<:Union{FieldElem, Float64}
+    visualize(P::Union{Polyhedron{T}, Cone{T}, PolyhedralFan{T}, PolyhedralComplex{T}, SubdivisionOfPoints{T}}; kwargs...) where T<:Union{FieldElem, Float64}
 
 Visualize a polyhedral object of dimension at most four (in 3-space).
 In dimensions up to 3 a usual embedding is shown.
 Four-dimensional polytopes are visualized as a Schlegel diagram, which is a projection onto one of the facets; e.g., see Chapter 5 of [Zie95](@cite).
 
 In higher dimensions there is no standard method; use projections to lower dimensions or try ideas from [GJRW10](@cite).
+
+# Extended help
+
+# Keyword Arguments
+
+## Colors
+
+Colors can be given as
+- a literal `String`, e.g. `"green"`.
+- a `String` of the format `"r g b"` where $r, g, b \in {0, \dots, 255}$ are integers corresponding to the R/G/B values of the color.
+- a `String` of the format `"r g b"` where $r, g, b \in [0, 1]$ are decimal values corresponding to the R/G/B values of the color.
+
+Possible arguments are:
+
+- `FacetColor`: Filling color of the polygons.
+- `EdgeColor`: Color of the boundary lines.
+- `PointColor`/`VertexColor`: Color of the spheres or rectangles representing the points.
+
+## Scaling and other gradient properties
+
+These arguments can be given as a floating point number:
+
+- `FacetTransparency`: Transparency factor of the polygons between 0 (opaque) and 1 (completely translucent).
+- `EdgeThickness`: Scaling factor for the thickness of the boundary lines.
+- `PointThickness`/VertexThickness`: Scaling factor for the size of the spheres or rectangles representing the points.
+
+## Camera
+
+These arguments can be given as a 3-element vector over floating point numbers:
+
+- `ViewPoint`: Position of the camera.
+- `ViewDirection`: Direction of the camera.
+
+## Appearance and Texts
+
+These arguments can be given as a string:
+
+- `FacetStyle`: If set to `"hidden"`, the inner area of the polygons are not rendered at all.
+- `FacetLabels`: If set to `"hidden"`, the facet labels are not displayed (in the most cases this is the default behavior). TODO
+- `EdgeStyle`: If set to `"hidden"`, the boundary lines are not rendered.
+- `Name`: The name of this visual object in the drawing.
+- `PointLabels`/`VertexLabels`: If set to `"hidden"`, no point labels are displayed.
+- `PointStyle`/`VertexStyle`: If set to `"hidden"`, neither point nor its label is rendered.
+- `LabelAlignment`: Defines the alignment of the vertex labels: `"left"`, `"right"` or `"center"`.
 """
 function visualize(
-  P::Union{Polyhedron{T},Cone{T},PolyhedralFan{T},PolyhedralComplex{T}}
-) where {T<:Union{Float64,FieldElem}}
+  P::Union{
+    Polyhedron{<:Union{Float64,FieldElem}},
+    Cone{<:Union{Float64,FieldElem}},
+    PolyhedralFan{<:Union{Float64,FieldElem}},
+    PolyhedralComplex{<:Union{Float64,FieldElem}},
+    SubdivisionOfPoints{<:Union{Float64,FieldElem}},
+    Graph,
+    SimplicialComplex,
+  };
+  kwargs...,
+)
+  _prepare_visualization(P)
+  pmo = pm_object(P)
+  Polymake.visual(pmo; kwargs...)
+end
+
+function visualize(P::Vector; kwargs::Dict=Dict{Int,Nothing}())
+  for p in P
+    @req p isa visual_supported_types "Can not visualize objects of type $(typeof(P))"
+    _prepare_visualization(p)
+  end
+  vis = [
+    Polymake.visual(
+      Polymake.Visual, pm_object(P[i]); get(kwargs, i, Vector{Nothing}(undef, 0))...
+    ) for i in 1:length(P)
+  ]
+  if isdefined(Main, :IJulia) && Main.IJulia.inited
+    # this will return a visual object,
+    # the visualization is then triggered by the show method
+    return Polymake.call_function(:common, :compose, vis...)
+  else
+    # this will call visual in void context and trigger the background viewer
+    Polymake.call_function(Nothing, :common, :compose, vis...)
+    return nothing
+  end
+end
+
+function _prepare_visualization(
+  P::Union{
+    Polyhedron{<:Union{Float64,FieldElem}},
+    Cone{<:Union{Float64,FieldElem}},
+    PolyhedralFan{<:Union{Float64,FieldElem}},
+    PolyhedralComplex{<:Union{Float64,FieldElem}},
+  },
+)
   d = ambient_dim(P)
   b = P isa Polyhedron
   if b && d == 4
@@ -23,11 +112,9 @@ function visualize(
   if !Polymake.exists(pm_object(P), "RAY_LABELS")
     pm_object(P).RAY_LABELS = string.(1:(Oscar.pm_object(P).N_RAYS))
   end
-  pmo = pm_object(P)
-  Polymake.visual(pmo)
 end
 
-function visualize(P::SubdivisionOfPoints{T}) where {T<:Union{FieldElem,Float64}}
+function _prepare_visualization(P::SubdivisionOfPoints{<:Union{Float64,FieldElem}})
   d = ambient_dim(P)
   @req d <= 3 "Can not visualize $(typeof(P)) of ambient dimension $d. Supported range: 1 <= d <= 3"
   # polymake will by default use 0:n-1 as labels so we assign labels
@@ -36,6 +123,8 @@ function visualize(P::SubdivisionOfPoints{T}) where {T<:Union{FieldElem,Float64}
   if !Polymake.exists(pm_object(P), "POINT_LABELS")
     pm_object(P).POINT_LABELS = string.(1:(Oscar.pm_object(P).N_POINTS))
   end
-  pmo = pm_object(P)
-  Polymake.visual(pmo)
+end
+
+function _prepare_visualization(P::Union{Graph,SimplicialComplex})
+  return nothing
 end