---
title: "CTTIR v5 and project logos"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{CTTIR v5 and project logos}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
resource_files:
  - figures/logo.svg
  - figures/logo-dark.svg
---

<!-- cttir-vignette-logo: start -->
<style>
.cttir-vignette-logo { float: right; width: 120px; max-width: 30%; margin: 0 0 1rem 1.5rem; }
.cttir-vignette-logo img { width: 100%; height: auto; border: 0; background: transparent; box-shadow: none; }
.cttir-vignette-logo .cttir-vignette-logo-light { display: block; }
.cttir-vignette-logo .cttir-vignette-logo-dark { display: none; }
@media (prefers-color-scheme: dark) {
  .cttir-vignette-logo .cttir-vignette-logo-light { display: none; }
  .cttir-vignette-logo .cttir-vignette-logo-dark { display: block; }
}
[data-bs-theme="light"] .cttir-vignette-logo .cttir-vignette-logo-light { display: block; }
[data-bs-theme="light"] .cttir-vignette-logo .cttir-vignette-logo-dark { display: none; }
[data-bs-theme="dark"] .cttir-vignette-logo .cttir-vignette-logo-light { display: none; }
[data-bs-theme="dark"] .cttir-vignette-logo .cttir-vignette-logo-dark { display: block; }
</style>
<div class="cttir-vignette-logo">
  <img class="cttir-vignette-logo-light" src="figures/logo.svg" alt="hexmakR logo" width="120" height="139" />
  <img class="cttir-vignette-logo-dark" src="figures/logo-dark.svg" alt="hexmakR logo" width="120" height="139" />
</div>
<!-- cttir-vignette-logo: end -->

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(hexmakR)
```

## Create first, reuse when useful

A new project starts with its own name and frame, without an archived motif:

```{r fresh-project}
project <- logo_design("My project", shape = "pentagon")
project <- hex_add_part(project, "circle", x = .5, y = .6, r = .15)
project <- hex_add_part(project, "polygon",
                        x = c(.35, .65, .5), y = c(.45, .45, .75))
hex_layers(project)
```

Hexagons, regular pentagons and squares share the same object, editing API
and export formats. The name is inside the lower part of the frame, and the
exterior is transparent. `layout = "motif"` creates a transparent square
without a frame or name. Add primitives there to work from an empty canvas.

## Browse the archive

The v5 library contains 45 identities. Their 270 original SVG and 270 PDF
masters are included unchanged in a compressed archive; `hex_asset()` returns
copies of them and renders the PNG versions from the SVG masters, and the five
icon sizes with the package renderer, on demand. Light, dark and
monochrome named masters keep the exact package name inside the hex.

```{r catalogue}
head(hex_catalog())
```

An explicit identity starts from its editable native R design; original
approved assets can be located separately:

```{r archive-design, eval=FALSE}
archived <- hex_design("phenoscapR")
print(archived)
hex_asset("phenoscapR", mode = "dark", layout = "lockup", format = "svg")
```

`hex_design()` without an explicit package also starts fresh. For a named
project, `logo_design("My project")` makes that intent explicit. Supply
`motif = "phenoscapR"` only when its full motif should be the starting point;
`icon = "microscope"` instead selects a generic icon.

## Reuse selected components

```{r reusable-parts}
archived <- hex_design("phenoscapR")
source_layers <- hex_layers(archived)
source_layers[source_layers$role == "motif", c("id", "type", "points")]
first_motif <- source_layers$id[source_layers$role == "motif"][1]
project <- hex_reuse_part(project, archived, first_motif)
```

Omit `layer` to import every motif component, excluding the source frame and
name:

```{r whole-motif, eval=FALSE}
project <- hex_reuse_part(project, "phenoscapR")
```

The destination keeps its name, frame, palette and existing parts. Each
import stores a validated snapshot of native source settings and edits, and
remains independently editable. Imported colours therefore stay as chosen
in the source until you edit those parts. Changing an archive selection does
not alter imported artwork.

## Edit, duplicate and remove

```{r part-edits}
project <- hex_edit_layer(project, "part_0001",
                          fill = "#45B59A", dx = .03, scale = .9)
project <- hex_duplicate_part(project, "part_0001")
hex_layers(project)
```

Use current IDs from `hex_layers()`. Native geometry uses `layer_` IDs;
additional primitives and imported components use `part_` IDs. Adding or
removing another part retains the IDs of existing parts.

`hex_edit_layer()` accepts fill, outline, line width, opacity, visibility,
translation, scale, rotation (`angle`) and explicit X/Y point coordinates. Coordinates are local
to the part's viewport; supply the same number of points. The input design
is unchanged, so keeping an earlier object provides undo in R.

```{r remove-part, eval=FALSE}
project <- hex_remove_part(project, "part_0002")
```

Removing an added part deletes it. Removing a native part hides it with a
saved visibility override. `hex_edit_layer(design, id, reset = TRUE)` removes
that part's overrides. Review edited scientific shapes at full size and icon
size because a changed silhouette can imply a different meaning.

## Portable projects and exports

Upload local figures and vector artwork with the same project API:

```{r imported-art, eval=FALSE}
project <- hex_import_art(project, "figure.svg")  # also PNG or JPEG
project <- hex_label_layer(project, "part_0001", "Central cell")
project <- hex_edit_layer(project, "part_0001", angle = 20, alpha = .8)
hex_groups(project)
project <- hex_group_layers(project, c("part_0001", "part_0002"), "Cells")
```

PNG/JPEG becomes one image part with embedded bytes; supported SVG shapes
become independently editable vector paths. Neither needs its original file
after import. SVG curves use bounded vector polylines. Solid fills/strokes,
transforms and local references are supported. Outline text and flatten
gradients, masks, filters, group opacity or intersecting clips first; unsupported
features produce an error. Uploads are capped at 10 MiB and rasters at 8192
pixels per side and 16 million pixels total. See `?hex_import_art` for the
complete supported subset and bounds.

```{r save-and-export, eval=FALSE}
hex_save_design(project, "project.json")
restored <- hex_read_design("project.json")
hex_export(restored, "project.svg")
hex_export(restored, "project.png", width = 1600)
hex_export(restored, "project.pdf")
hex_recipe(restored, "reproduce.R")
```

JSON contains only supported settings, geometry and source snapshots. It
never loads executable R, external files or serialised grid objects. Unknown
fields, nested archive parts, invalid coordinates and projects over 20 MiB are
rejected. Earlier v5 JSON files remain supported and retain their archived
motif behaviour.

The bundled JetBrains Mono font supplies outlined name glyphs. Vector
exports do not depend on installed fonts. Font licences are supplied under
`system.file("cttir/source/fonts", package = "hexmakR")`. Hex canvases use
width/height `sqrt(3)/2`; pentagon, square and unframed canvases are square.

## Manual editor

```{r editor, eval=FALSE}
hexmakr_app()
hexmakr_app(package = "phenoscapR")  # preselect CTTIR Gallery; Designer stays fresh
```

The Designer starts with a new logo. Apply its name and frame, add parts,
then select, drag and edit individual components. Short labels and editable
groups organise the composition. CTTIR Gallery browsing leaves the logo
unchanged; adding a selected part, adding a motif, and starting from a whole
archive design are separate explicit actions.

**Undo** restores applied actions. **Reset to starting design** returns to
the fresh, explicitly loaded archive or opened-project baseline. **Save
project** and **Open saved project** preserve editable parts. Downloads use
the applied design, so apply pending form changes first. The classic
workspace remains available as `hexmakr_app(workspace = "classic")`.

## Original catalogue and legacy references

```{r regenerate, eval=FALSE}
# 45 x (2 layouts x 3 modes x 3 formats + 5 icons) = 1,035 exports
hex_render_catalog("exports")
```

This regenerates designs from native R geometry. Use `hex_asset()` when the
unchanged approved master is required.

The twelve names present only in the older hexstickers repository remain
legacy SVG references under `inst/cttir/legacy` in the source repository.
They are not claimed as approved v5 motifs. `hexmakeR` maps to `hexmakR`;
`delphyR` maps to `delphyr`.

`CTTIR` and `cttiR` differ only in case. The organisation's asset directory is
`CTTIR-brand`; the R package retains `cttiR`. `hex_catalog()$asset_dir` records
this mapping to prevent collisions on macOS and Windows. Display names keep
their exact spelling. Archive and asset hashes record the supplied originals.