This chapter gives some demonstration on the various possibilities offered by the Polygon class. Remember that the Polygon is an item which is specifically defined in 2-D space. However an extension to 3-D space has been programmed: the polyhedron is regarded as a 3-D object with a polygonal trace in the 2-D plane and a limite extension along the third direction.

In this tutorial, we concentrate on the 2-D case.

defineDefaultSpace(ESpaceType_RN(), 2)
## NULL

To visualize the impact of the polygons, it is usual to check its impact on a Db (a Grid one makes the demonstration more efficient). Moreover it makes sense to generate a variable which presents some spatial continuity on this grid, such as a variable created by simulation.

mygrid = DbGrid_create(nx=c(150,100),dx=c(1,1))
mymodel = Model_createFromParam(ECov_CUBIC(), range=30, sill=1)
err = simtub(NULL,mygrid,mymodel)

The variable (called Simu) defined on the grid is visualized first.

ggplot() + plot.grid(mygrid, palette="inferno")

We now define the items of the PolyGon class. Let us recall that a polygon is a set of PolyElems. Each PolyElem is defined by a series of 2-D points which serve as vertices. The PolyElem can be closed or not (it will be closed automatically if necessary, depending on its usage). The Polygon (in broad sense) can be used essentially; - for visualization purpose - to apply a selection on the elements of a Db: we will apply it on the nodes of our grid for demonstration sake.

Let us start by a simple polygon constituted of a single PolyElem.

polygon = Polygons()
polyelem1 = PolyElem(x=c(40, 75, 100, 15), y = c(25, 10, 75, 60))
polygon$addPolyElem(polyelem1)
## NULL

Displaying the contents of the polygon:

polygon$display()
## 
## Polygons
## --------
## Number of Polygon Sets = 1
## NULL
polygon$display(AStringFormat(level=2))
## 
## Polygons
## --------
## Number of Polygon Sets = 1
## 
## PolyElem #1
## ...........
## Number of Vertices = 4
## NULL

Some nice features are available such as:

polygon$getSurface()
## [1] 1325

We can now overlay the polygon (filled in "yellow") on top of the grid

p = ggplot()
p = p + plot.grid(mygrid, palette="inferno")
p = p + plot.polygon(polygon, fill="yellow")
ggPrint(p)

More interesting is to use this polygon in order to create a selection on the grid nodes. Then the only nodes lying within the polygon will be considered as active.

db_polygon(mygrid, polygon)
## NULL
mygrid
## 
## Data Base Grid Characteristics
## ==============================
## 
## Data Base Summary
## -----------------
## File is organized as a regular grid
## Space dimension              = 2
## Number of Columns            = 5
## Total number of samples      = 15000
## Number of active samples     = 3006
## 
## Grid characteristics:
## ---------------------
## Origin :      0.000     0.000
## Mesh   :      1.000     1.000
## Number :        150       100
## 
## Variables
## ---------
## Column = 0 - Name = rank - Locator = NA
## Column = 1 - Name = x1 - Locator = x1
## Column = 2 - Name = x2 - Locator = x2
## Column = 3 - Name = Simu - Locator = z1
## Column = 4 - Name = Polygon - Locator = sel

Displaying the grid (taking the selection into account) is performed now. Note that the polygon is overlaid again but in a transparent mode

p = ggplot()
p = p + plot.grid(mygrid, palette="inferno")
p = p + plot.polygon(polygon, fill=NA, color="yellow", linewidth=2)
ggPrint(p)

Let us make the polygon more complex by adding other PolyElems which partly overlay each one another.

polyelem2 = PolyElem(x=c(50, 100, 100, 50), y=c(30, 30, 55, 55))
polygon$addPolyElem(polyelem2)
## NULL
polyelem3 = PolyElem(x=c(25, 100, 55), y=c(25,25, 80))
polygon$addPolyElem(polyelem3)
## NULL
polygon$display(AStringFormat(level=2))
## 
## Polygons
## --------
## Number of Polygon Sets = 3
## 
## PolyElem #1
## ...........
## Number of Vertices = 4
## 
## PolyElem #2
## ...........
## Number of Vertices = 4
## 
## PolyElem #3
## ...........
## Number of Vertices = 3
## NULL

In the following figure, we display the edges of the different PolyElems

ggplot() + plot.polygon(polygon, fill=NA)

Obviously, the three olyElems of the polygon overlay. So the impact of using this polygon for selection will be interesting.

In this first example, the selection algorithm is quite simple: a grid node is considered as active as soon as it belongs to one of the PolyElems

db_polygon(mygrid, polygon)
## NULL
ggplot() + plot.grid(mygrid, palette="inferno")

In the second example: * a grid node is considered as active if the number of PolyElems to which it belongs is odd*. This feature enables a polygon to contain holes as demonstrated in the next example

db_polygon(mygrid, polygon, flag_nested=TRUE)
## NULL
ggplot() + plot.grid(mygrid, palette="inferno")

An interesting function allows checking if a point (characterized by its 2-D coordinates) belongs to the polygon or not.

xx = 75
yy = 50
flag_nested = FALSE
inside = polygon$inside(c(xx, yy), flag_nested=flag_nested)
cat("Is the Point (",xx,",",yy,") with flag_nested =",flag_nested,", inside the Polygon =",inside,"\n")
## Is the Point ( 75 , 50 ) with flag_nested = FALSE , inside the Polygon = TRUE
xx = 40
yy = 40
flag_nested = FALSE
inside = polygon$inside(c(xx, yy), flag_nested=flag_nested)
cat("Is the Point (",xx,",",yy,") with flag_nested =",flag_nested,", inside the Polygon =",inside,"\n")
## Is the Point ( 40 , 40 ) with flag_nested = FALSE , inside the Polygon = TRUE
flag_nested = TRUE
inside = polygon$inside(c(xx, yy), flag_nested=flag_nested)
cat("Is the Point (",xx,",",yy,") with flag_nested =",flag_nested,", inside the Polygon =",inside,"\n")
## Is the Point ( 40 , 40 ) with flag_nested = TRUE , inside the Polygon = FALSE