---
title: "Creating String Art Figures with stringArt"
author: "Ivo Moreira Barbosa and Fernando de Souza Bastos"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Creating String Art Figures with stringArt}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6.5,
  fig.height = 6.5,
  fig.align = "center",
  out.width = "80%",
  dpi = 96
)

library(stringArt)
```

## Introduction

The `stringArt` package was developed as part of the Professional Master's Program in Mathematics in National Network (PROFMAT). It is one of the results of the master's dissertation of Ivo Moreira Barbosa, under the supervision of Professor Fernando de Souza Bastos, from the Department of Statistics of the Federal University of Viçosa.

The purpose of the project is to provide a pedagogical product that supports mathematics teachers in the teaching of Geometry and related mathematical concepts through a playful, visual, practical, and computational approach. The package combines the artistic appeal of String Art with mathematical ideas such as points, segments, polygons, modular arithmetic, symmetry, envelopes of straight lines, cycles, and total string length.

The package also supports the production of peg templates, connection tables, audit information, and interactive visualizations through a Shiny application. The main goal is to help teachers create classroom activities in which students can move between concrete manipulation, visual exploration, and mathematical reasoning.

## General structure

The functions in `stringArt` follow a common interface whenever possible. The main arguments are:

- `n`: number of pegs or points;
- `k`: step, factor, or rule used to create the connections;
- `col`: line color;
- `lwd`: line width;
- `plot`: whether the figure should be plotted;
- `show_points`: whether the pegs should be shown;
- `show_labels`: whether the peg labels should be shown;
- `verbose`: whether detailed audit information should be printed.

Each function returns an invisible list containing at least:

- `pegs`: coordinates and identifiers of the pegs;
- `connections`: table with the string connections;
- `total_length`: total string length;
- `audit`: audit information about the construction;
- `meta`: metadata about the figure and parameters.

For compatibility with previous versions and with the Shiny application, returned objects may also include Portuguese aliases such as `pregos`, `conexoes`, and `comprimento_total`.

## Circular String Art

The function `stcircle()` creates pegs equally spaced on a circle and connects each peg to another peg according to an additive modular step. This is useful for exploring modular arithmetic, cycles, symmetry, and polygons.

```{r stcircle-basic, fig.cap = "Circular String Art generated by additive modular connections."}
stcircle(
  n = 60,
  k = 17,
  col = "steelblue",
  lwd = 0.8,
  show_points = TRUE,
  show_labels = FALSE,
  verbose = FALSE
)
```

The result can also be stored without producing a plot.

```{r stcircle-object}
circle_res <- stcircle(
  n = 24,
  k = 5,
  col = "steelblue",
  lwd = 1,
  plot = FALSE,
  verbose = FALSE
)

names(circle_res)
head(circle_res$connections)
circle_res$total_length
```

## Cardioid-like String Art

The function `stcardioid()` creates a circular String Art figure using a multiplicative modular rule. This construction is useful for exploring multiplication tables, modular arithmetic, cycles, and cardioid-like visual patterns.

```{r stcardioid-basic, fig.cap = "Cardioid-like String Art generated by a multiplicative modular rule."}
stcardioid(
  n = 120,
  k = 2,
  col = "darkorange",
  lwd = 0.7,
  show_points = FALSE,
  show_labels = FALSE,
  verbose = FALSE
)
```

The value of `k` changes the multiplication rule and generates different visual structures.

```{r stcardioid-factor, fig.cap = "Cardioid-like String Art with a different multiplicative factor."}
stcardioid(
  n = 150,
  k = 3,
  col = "purple",
  lwd = 0.6,
  show_points = FALSE,
  show_labels = FALSE,
  verbose = FALSE
)
```

## Elliptical String Art

The function `stellipse()` places pegs on an ellipse and connects them according to an additive modular step. This figure extends the circular construction to an elliptical frame and supports discussions about parametric curves, scaling, and geometric transformations.

```{r stellipse-basic, fig.cap = "Elliptical String Art generated by additive modular connections."}
stellipse(
  n = 80,
  k = 23,
  a = 1.6,
  b = 1,
  col = "forestgreen",
  lwd = 0.8,
  show_points = TRUE,
  show_labels = FALSE,
  verbose = FALSE
)
```

## Triangular String Art

The function `sttriangle()` places pegs along the boundary of an equilateral triangle. The connections are generated according to a step rule and may be used to explore polygons, perimeter, symmetry, and geometric patterns on triangular frames.

```{r sttriangle-basic, fig.cap = "String Art on an equilateral triangular frame."}
sttriangle(
  n = 90,
  k = 29,
  col = "firebrick",
  lwd = 0.8,
  show_points = TRUE,
  show_labels = FALSE,
  verbose = FALSE
)
```

## Hexagonal flower

The function `sthexaflower()` generates a figure based on concentric hexagonal circuits. It is useful for exploring symmetry, rotations, repeated patterns, and geometric structures related to regular polygons.

```{r sthexaflower-basic, fig.cap = "Hexagonal flower String Art pattern."}
sthexaflower(
  n = 96,
  k = 17,
  col = "dodgerblue4",
  lwd = 0.8,
  show_points = FALSE,
  show_labels = FALSE,
  verbose = FALSE
)
```

## Radial String Art

The function `stradial()` generates rotated triangular or radial modules. This construction supports discussions about rotations, angular displacement, repeated modules, and visual composition.

```{r stradial-basic, fig.cap = "Radial String Art generated from rotated modules."}
stradial(
  n = 72,
  k = 19,
  col = "darkmagenta",
  lwd = 0.8,
  show_points = FALSE,
  show_labels = FALSE,
  verbose = FALSE
)
```

## Region-based String Art

The function `stregion()` places pegs along a contour. If no contour is supplied, the function uses a default contour. This allows teachers to explore String Art beyond standard geometric frames and connect the construction with curves, boundaries, and customized shapes.

```{r stregion-basic, fig.cap = "String Art generated from a default contour."}
stregion(
  n = 100,
  k = 31,
  col = "black",
  lwd = 0.7,
  show_points = FALSE,
  show_labels = FALSE,
  verbose = FALSE
)
```

A custom contour may also be used, depending on the implementation of the function. The general idea is to provide a set of ordered boundary points and let the function sample pegs along this contour.

```{r stregion-custom, eval = FALSE}
theta <- seq(0, 2 * pi, length.out = 200)

custom_contour <- data.frame(
  x = cos(theta) * (1 + 0.25 * cos(5 * theta)),
  y = sin(theta) * (1 + 0.25 * cos(5 * theta))
)

stregion(
  contour = custom_contour,
  n = 120,
  k = 37,
  col = "tomato",
  lwd = 0.7,
  show_points = FALSE,
  show_labels = FALSE
)
```

## Peg templates

In addition to complete String Art figures, the package can be used to produce peg templates without strings. This is useful when the teacher wants to print a template for a manual classroom activity.

Depending on the final implementation of each function, this can be done either by using a specific argument for templates or by plotting the pegs from the returned object.

```{r peg-template, fig.cap = "Example of a peg template produced from a returned object."}
template_res <- stcircle(
  n = 36,
  k = 7,
  plot = FALSE,
  verbose = FALSE
)

plot(
  template_res$pegs$x,
  template_res$pegs$y,
  asp = 1,
  pch = 19,
  xlab = "",
  ylab = "",
  axes = FALSE,
  main = "Peg template"
)

text(
  template_res$pegs$x,
  template_res$pegs$y,
  labels = template_res$pegs$id,
  pos = 3,
  cex = 0.7
)
```

## Audit and connection table

The returned object makes it possible to inspect the construction numerically. This is useful for connecting the artistic object with mathematical reasoning.

```{r audit-and-connections}
res <- stcircle(
  n = 12,
  k = 5,
  col = "steelblue",
  lwd = 1,
  plot = FALSE,
  verbose = FALSE
)

res$total_length
res$audit
res$connections
```

The connection table can be used to discuss the order of the strings, the length of each segment, and the total amount of string needed to construct the figure physically.

## Shiny application

The package also includes an interactive Shiny application. After installing the package, the app can be launched locally with:

```{r shiny-app, eval = FALSE}
stringArt::run_stringArt_app()
```

The Shiny interface was designed as a simple classroom-oriented product. Its main controls are:

- number of pegs;
- step or factor;
- line color;
- line width;
- show pegs;
- show labels;
- show peg template without strings;
- show audit in the console.

The Shiny app is not required to use the package functions. It is provided as an additional educational interface for teachers and students.

## Final remarks

The `stringArt` package was designed to support the teaching and learning of Mathematics through an approach that combines computation, visual thinking, and hands-on activity. The package allows teachers to generate complete String Art figures, peg templates, connection tables, and total string length information.

In classroom practice, these resources can be used to promote mathematical investigation, student engagement, and connections between Geometry, modular arithmetic, symmetry, and artistic creation.