---
title: "Calculates the fractal dimension of 2D and 3D (sliced) images"
author: "Francesco Paolo Mancuso"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Calculates the fractal dimension of 2D and 3D (sliced) images}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The package `fractD` contains two fuctions `fract2D` and `fract3D` that allow to estimate the fractal dimension (D) of 2D and 3D images. Fractal dimension is estimated by the method of box-counting. Box-counting method is useful to calculate the fractal dimension of various sets of any dimension and patterns with or without  self-similarity (Klinkenberg, 1994). The method overlay a series of squares (for `fract2D`) or cubes (for `fract3D`) of different sizes. Then, for each size step the functions keep track of the number of squares or cubes occupied by the black area into the image. Finally, the fractal dimension (D) is estimated by linear regression of log(n°boxes) on log(box.size).

The following illustration show the rational behind the function `fract2D`:

![](box-counting_2D_image.svg)


Here an example of applying `fract2D` to the following image:
![](eg_img.svg)

```{r example2D,results = "hide", message = FALSE, warning = FALSE}
library(fractD)
## basic example code for fract2D
fct2D <- fract2D(dir = "examples/source.dir", box.size = c(1,2,4,8,16,32,64,128,256,512))

## the following code saves the data in a file named "es3D.rds" into the "output"" folder 
## not run ## 
##fct2D <- fract2D(dir = "examples/source.dir", box.size = c(1,2,4,8,16,32,64,128,256,512), save.dir = "examples/output/", save.name = "es2D")
```

```{r}
# the function create a list with two objects: 
fct2D$D # Estimated fractal dimension

fct2D$raw.dat # Raw data from which fractal dimension was calculated 
```


The following illustration show the rational behind the function `fract3D`:

![](box-counting_3D_image.svg)

Here an example of applying `fract3D` to the following image:     

![](eg_img_slice.svg)


```{r example3D ,results = "hide", message = F, warning = F}
#library(fractD)
## basic example code for fract3D
# save.dir and save.name provide optional 
fct3D <- fract3D(dir = "examples/source.dir", dist.slice = 10, box.size = c(4,8,16,32,128,256,512))

# the following code saves the data in a file named "es3D.rds" into the "output"" folder 
## not run ## 
## fct3D <- fract3D(dir = "examples/source.dir", dist.slice = 1, box.size = c(1,2,4,8,16,32,64,128,256,512), save.dir = "examples/output/", save.name = "es3D")
```

```{r}
# the function create a list with two objects: 
fct3D$D # Estimated fractal dimension

fct3D$raw.dat # Raw data from which fractal dimension was calculated 
```

## References

* Mandelbrot B.B. (1982) - \emph{The fractal Geometry of Nature}. San Francisco: W.H. Freman.
* Klinkenberg B. (1994) - \emph{A Review of methods used to determine the fractal dimension of linear features}. Mathematical Geology, vol. 26, n° 1. doi: 10.1007/BF02065874
* Dubuc B., Quiniou J.F., Roques-Carmes C., Tricot C., Zucker S.W. (1989) - \emph{Evaluating the fractal dimension of profiles}. Physical Review A, vol. 39, n° 3. doi: 10.1103/PhysRevA.39.1500
* Taud H and Parrot J-F (2005) - \emph{Measurement of DEM roughness using the local fractal dimension}. Géomorphologie: relief, processus, environnement: 4, 327-338. doi: 10.4000/geomorphologie.622