docs/development-guides/hexagonal-code-snippets.md

# Hexagonal Puzzles - Useful Code Snippets

**Last Updated**: 2025-11-27

A collection of useful code patterns and "hacky" snippets extracted from development and debugging sessions.

---

## Quick Visualization

### Generate Test SVG

```r

# Quick test of hexagonal separation with bezier curves

source("R/hexagonal_topology.R")

source("R/hexagonal_neighbors.R")

source("R/hexagonal_bezier_generation.R")

source("R/hexagonal_edge_generation_fixed.R")

source("R/hexagonal_separation.R")



svg <- generate_separated_hexagonal_svg(

  rings = 2,

  seed = 42,

  diameter = 240,

  offset = 10,

  arrangement = "hexagonal",

  use_bezier = TRUE,

  tabsize = 27,

  jitter = 5

)



dir.create("output", showWarnings = FALSE)

writeLines(svg, "output/quick_test.svg")

cat("Saved to output/quick_test.svg\n")

```

### Create Standalone Bezier Visualization

```r

# Visualize hexagonal bezier pieces

source("R/hexagonal_topology.R")

source("R/hexagonal_bezier_generation.R")



pieces <- generate_all_hex_pieces_bezier(

  rings = 2,

  seed = 42,

  diameter = 240,

  separated = TRUE

)



# Calculate SVG dimensions

all_x <- sapply(pieces, function(p) p$center_x)

all_y <- sapply(pieces, function(p) p$center_y)

margin <- 50

min_x <- min(all_x) - margin

max_x <- max(all_x) + margin

min_y <- min(all_y) - margin

max_y <- max(all_y) + margin

width <- max_x - min_x

height <- max_y - min_y



# Create SVG

svg_content <- sprintf(

  '<?xml version="1.0" encoding="UTF-8"?>

<svg xmlns="http://www.w3.org/2000/svg" viewBox="%.2f %.2f %.2f %.2f">

  <style>

    .puzzle-piece { fill: white; stroke: black; stroke-width: 1; }

    .piece-label { font-family: Arial; font-size: 12px; text-anchor: middle; }

  </style>

  <rect x="%.2f" y="%.2f" width="%.2f" height="%.2f" fill="#f0f0f0"/>',

  min_x, min_y, width, height,

  min_x, min_y, width, height

)



for (p in pieces) {

  svg_content <- paste0(svg_content, sprintf(

    '\n  <path class="puzzle-piece" d="%s"/>

  <text class="piece-label" x="%.2f" y="%.2f">%d</text>',

    p$path, p$center_x, p$center_y, p$id

  ))

}



svg_content <- paste0(svg_content, '\n</svg>')

writeLines(svg_content, "output/bezier_visualization.svg")

```

---

## Coordinate System Analysis

### Analyze Grid Iteration Pattern

```r

# Understand piece numbering in hexagonal grid

source('R/hexagonal_puzzle.R')



analyze_hex_grid <- function(rings) {

  n <- rings

  yl <- 2 * n - 1



  cat(sprintf("Rings: %d\n", rings))

  cat(sprintf("yl = %d (2*n - 1)\n\n", yl))



  piece_id <- 1

  for (yi in seq(-yl + 2, yl - 2, by = 2)) {

    xl <- 2 * n - 1 - (abs(yi) - 1) / 2

    cat(sprintf("yi=%3d: xl=%.1f, xi range: [%.0f, %.0f]\n",

                yi, xl, -xl + 1, xl - 2))



    for (xi in seq(-xl + 1, xl - 2, by = 1)) {

      cat(sprintf("  Piece %2d: (xi=%.1f, yi=%d)\n", piece_id, xi, yi))

      piece_id <- piece_id + 1

    }

  }



  total <- 3 * rings * (rings - 1) + 1

  cat(sprintf("\nTotal pieces: %d\n", total))

}



analyze_hex_grid(2)  # 7 pieces

analyze_hex_grid(3)  # 19 pieces

```

### Map Piece IDs to Axial Coordinates

```r

# Convert piece ID to (q, r) axial coordinates

piece_to_axial <- function(piece_id, rings) {

  if (piece_id == 1) return(c(q = 0, r = 0))



  # Hexagonal directions (for ring traversal)

  hex_directions <- list(

    c(1, 0), c(1, -1), c(0, -1),

    c(-1, 0), c(-1, 1), c(0, 1)

  )



  remaining <- piece_id - 1

  ring <- 1



  while (remaining > 6 * ring) {

    remaining <- remaining - 6 * ring

    ring <- ring + 1

  }



  # Start position for this ring

  q <- 0

  r <- -ring



  position <- remaining - 1

  direction <- floor(position / ring)

  steps_in_direction <- position %% ring



  # Move to starting direction

  for (d in seq_len(direction)) {

    for (s in seq_len(ring)) {

      dir <- hex_directions[[d]]

      q <- q + dir[1]

      r <- r + dir[2]

    }

  }



  # Move within direction

  if (steps_in_direction > 0 && direction < 6) {

    dir <- hex_directions[[direction + 1]]

    for (s in seq_len(steps_in_direction)) {

      q <- q + dir[1]

      r <- r + dir[2]

    }

  }



  c(q = q, r = r)

}

```

---

## Debugging Utilities

### Debug Path Connectivity

```r

# Test if SVG paths connect at endpoints

debug_path_connectivity <- function(paths, tolerance = 0.5) {

  all_segs <- list()



  for (path in paths) {

    segs <- split_path_by_move(path)

    all_segs <- c(all_segs, segs)

  }



  cat(sprintf("Total segments: %d\n\n", length(all_segs)))



  # Print endpoints

  cat("Segment endpoints:\n")

  for (i in seq_along(all_segs)) {

    seg <- all_segs[[i]]

    cat(sprintf("  %d: (%.2f, %.2f) -> (%.2f, %.2f)\n",

                i, seg$start[1], seg$start[2],

                seg$end[1], seg$end[2]))

  }



  # Test connectivity

  cat("\nConnectivity test:\n")

  for (tol in c(0.1, 0.5, 1.0, 2.0, 5.0)) {

    connections <- 0

    for (i in seq_along(all_segs)) {

      for (j in seq_along(all_segs)) {

        if (i != j) {

          d <- sqrt(sum((all_segs[[i]]$end - all_segs[[j]]$start)^2))

          if (d < tol) connections <- connections + 1

        }

      }

    }

    cat(sprintf("  Tolerance %.1f: %d connections\n", tol, connections))

  }

}

```

### Debug Edge Complementarity

```r

# Verify edge complementarity between adjacent pieces

debug_edge_complementarity <- function(edge_data, piece1, side1, piece2, side2) {

  key1 <- sprintf("%d-%d", piece1, side1)

  key2 <- sprintf("%d-%d", piece2, side2)



  edge1 <- edge_data$piece_edge_map[[key1]]

  edge2 <- edge_data$piece_edge_map[[key2]]



  cat(sprintf("Checking: Piece %d side %d <-> Piece %d side %d\n",

              piece1, side1, piece2, side2))



  if (is.null(edge1)) {

    cat("  ERROR: edge1 not found\n")

    return(FALSE)

  }

  if (is.null(edge2)) {

    cat("  ERROR: edge2 not found\n")

    return(FALSE)

  }



  cat(sprintf("  Edge1 key: %s\n", edge1$edge_key))

  cat(sprintf("  Edge2 key: %s\n", edge2$edge_key))

  cat(sprintf("  Edge1 forward: %s...\n", substr(edge1$forward, 1, 50)))

  cat(sprintf("  Edge2 reverse: %s...\n", substr(edge2$reverse, 1, 50)))



  if (edge1$edge_key == edge2$edge_key && edge1$forward == edge2$reverse) {

    cat("  RESULT: COMPLEMENTARY\n")

    return(TRUE)

  } else {

    cat("  RESULT: NOT COMPLEMENTARY\n")

    return(FALSE)

  }

}

```

### Debug Piece Positions

```r

# Print all piece positions for verification

debug_piece_positions <- function(rings) {

  source("R/hexagonal_topology.R")



  num_pieces <- 3 * rings * (rings - 1) + 1



  cat(sprintf("Piece positions for %d rings (%d pieces):\n",

              rings, num_pieces))

  cat("=" * 50, "\n")



  for (i in seq_len(num_pieces)) {

    ring_info <- map_piece_id_to_ring(i, rings)

    pos <- calculate_hex_piece_position(i, rings, diameter = 240)



    cat(sprintf("Piece %2d: ring=%d, pos=%d, dir=%d, angle=%.0f°, ",

                i, ring_info$ring, ring_info$position_in_ring,

                ring_info$direction, ring_info$angle * 180 / pi))

    cat(sprintf("center=(%.1f, %.1f)\n", pos$x, pos$y))

  }

}



debug_piece_positions(2)

```

---

## Neighbor Detection

### Calculate Neighbors from Vertex Sharing

```r

# Find neighbors by checking shared vertices

find_neighbors_by_vertices <- function(pieces, tolerance = 0.5) {

  neighbors <- list()



  for (i in seq_along(pieces)) {

    neighbors[[i]] <- integer(0)

    vertices_i <- pieces[[i]]$vertices  # 6 vertices per hexagon



    for (j in seq_along(pieces)) {

      if (i == j) next



      vertices_j <- pieces[[j]]$vertices



      # Count shared vertices

      shared <- 0

      for (vi in seq_len(6)) {

        for (vj in seq_len(6)) {

          d <- sqrt(sum((vertices_i[, vi] - vertices_j[, vj])^2))

          if (d < tolerance) shared <- shared + 1

        }

      }



      # Adjacent hexagons share exactly 2 vertices (one edge)

      if (shared >= 2) {

        neighbors[[i]] <- c(neighbors[[i]], j)

      }

    }

  }



  neighbors

}

```

### Ring 1 to Ring 2 Neighbor Mapping

```r

# Quick lookup for ring 1 neighbors in ring 2

get_ring2_neighbors_of_ring1 <- function(ring1_piece) {

  # Piece 2 (ring 1, position 0): neighbors pieces 8, 9 in ring 2

  # Piece 3 (ring 1, position 1): neighbors pieces 10, 11 in ring 2

  # etc.



  ring1_position <- ring1_piece - 2  # 0-5

  ring2_start <- 8  # First piece in ring 2



  # Each ring 1 piece neighbors 2 consecutive ring 2 pieces

  c(ring2_start + ring1_position * 2,

    ring2_start + ring1_position * 2 + 1)

}

```

---

## SVG Path Manipulation

### Parse SVG Path Commands

```r

# Extract commands and coordinates from SVG path

parse_svg_path <- function(path) {

  # Split by command letters

  commands <- strsplit(path, "(?=[MLCQSZ])", perl = TRUE)[[1]]

  commands <- commands[nchar(commands) > 0]



  result <- list()

  for (cmd in commands) {

    type <- substr(cmd, 1, 1)

    coords_str <- trimws(substr(cmd, 2, nchar(cmd)))

    coords <- as.numeric(strsplit(coords_str, "[, ]+")[[1]])

    coords <- coords[!is.na(coords)]



    result[[length(result) + 1]] <- list(type = type, coords = coords)

  }



  result

}



# Example usage:

# parsed <- parse_svg_path("M 10 20 L 30 40 C 50 60 70 80 90 100")

# parsed[[1]]  # list(type = "M", coords = c(10, 20))

```

### Translate SVG Path

```r

# Move entire SVG path by (dx, dy)

translate_svg_path <- function(path, dx, dy) {

  parsed <- parse_svg_path(path)



  result <- ""

  for (cmd in parsed) {

    if (cmd$type == "Z") {

      result <- paste0(result, "Z ")

      next

    }



    coords <- cmd$coords



    # Translate coordinates (every pair)

    for (i in seq(1, length(coords), by = 2)) {

      coords[i] <- coords[i] + dx

      coords[i + 1] <- coords[i + 1] + dy

    }



    result <- paste0(result, cmd$type, " ",

                     paste(sprintf("%.2f", coords), collapse = " "), " ")

  }



  trimws(result)

}

```

### Reverse SVG Path

```r

# Reverse direction of SVG path (for complementary edges)

reverse_svg_path <- function(path) {

  parsed <- parse_svg_path(path)



  # Collect all points

  points <- list()

  for (cmd in parsed) {

    if (cmd$type == "M" || cmd$type == "L") {

      points[[length(points) + 1]] <- cmd$coords

    } else if (cmd$type == "C") {

      # Cubic bezier: 3 coordinate pairs

      points[[length(points) + 1]] <- cmd$coords[1:2]  # control 1

      points[[length(points) + 1]] <- cmd$coords[3:4]  # control 2

      points[[length(points) + 1]] <- cmd$coords[5:6]  # end point

    }

  }



  # Reverse and rebuild

  points <- rev(points)

  # ... rebuild path from reversed points

  # (Implementation depends on curve type)

}

```

---

## Quick Tests

### Test Shiny App Flow

```r

# Trace through Shiny app generation flow

test_shiny_flow <- function() {

  cat("Testing Shiny app flow:\n")



  # Simulate input

  rings <- 2

  seed <- 42

  diameter <- 240

  offset <- 10

  use_bezier <- TRUE



  cat("1. Generating SVG...\n")

  svg <- generate_separated_hexagonal_svg(

    rings = rings,

    seed = seed,

    diameter = diameter,

    offset = offset,

    arrangement = "hexagonal",

    use_bezier = use_bezier

  )



  cat("2. Checking SVG content...\n")

  cat(sprintf("   Length: %d characters\n", nchar(svg)))

  cat(sprintf("   Has bezier: %s\n", grepl("C ", svg)))

  cat(sprintf("   Piece count: %d\n", length(gregexpr("<path", svg)[[1]])))



  cat("3. Saving output...\n")

  writeLines(svg, "output/shiny_flow_test.svg")

  cat("   Saved to output/shiny_flow_test.svg\n")



  cat("\nTest complete!\n")

}

```

### Final Verification Script

```r

# Comprehensive verification of hexagonal implementation

final_verification <- function() {

  source("R/hexagonal_topology.R")

  source("R/hexagonal_neighbors.R")

  source("R/hexagonal_bezier_generation.R")

  source("R/hexagonal_edge_generation_fixed.R")

  source("R/hexagonal_separation.R")



  cat("=" * 60, "\n")

  cat("  FINAL VERIFICATION - Hexagonal Implementation\n")

  cat("=" * 60, "\n\n")



  # Test 1: Generate puzzle

  cat("Test 1: Generate 2-ring puzzle with bezier\n")

  svg <- generate_separated_hexagonal_svg(

    rings = 2, seed = 42, diameter = 240, offset = 10,

    arrangement = "hexagonal", use_bezier = TRUE

  )

  cat(sprintf("  SVG length: %d chars\n", nchar(svg)))

  cat(sprintf("  Has bezier curves: %s\n", grepl("C ", svg)))



  # Test 2: Edge complementarity

  cat("\nTest 2: Edge complementarity\n")

  edge_data <- generate_hex_edge_map(rings = 2, seed = 42, diameter = 240)

  cat(sprintf("  Generated %d unique edges\n", edge_data$num_edges))



  # Test 3: Save output

  cat("\nTest 3: Save verification output\n")

  output_file <- "output/final_verification.svg"

  writeLines(svg, output_file)

  cat(sprintf("  Saved: %s\n", output_file))



  cat("\n")

  cat("=" * 60, "\n")

  cat("  ALL TESTS PASSED\n")

  cat("=" * 60, "\n")

}



# Run with: final_verification()

```

---

*Add new snippets as they're discovered during development.*