modFrames

Shiny UI module for the Artalytics platform providing frame comparison, timelapse playback, and AI-powered creative journey storytelling.

System Requirements

CRITICAL: modFrames requires the ImageMagick++ C++ library for frame difference visualization: Linux (Debian/Ubuntu):

sudo apt install libmagick++-dev

macOS:

brew install imagemagick

Windows: Download and install ImageMagick with C++ headers from imagemagick.org. Ensure “Install development headers and libraries for C and C++” is checked.

Installation

# Requires GITHUB_PAT for private repo access
pak::pkg_install("artalytics/modFrames")

Features

• Timelapse Playback: Animated frame-by-frame visualization with real-time metrics (strokes, elapsed time, unique colors)
• Frame Comparison: Side-by-side comparison with visual difference highlighting using ImageMagick
• Creative Journey Storytelling: Marketing-ready narrative insights generated from frame analytics
• Interactive Visualization: Plotly-powered color evolution charts

Quick Example

library(shiny)
library(bslib)
library(modFrames)

ui <- bslib::page_fluid(
  modFramesUI("frames")
)

server <- function(input, output, session) {
  r <- reactiveValues()

  observe({
    r$appdata <- artutils::get_appdata(
      artist = "746b8207-72f5-4ab6-8d19-a91d03daec3d",
      artwork = "99da02ea-1ac0-4ea0-bfb9-e11a485b599b"
    )
  })

  modFramesServer("frames", r)
}

shinyApp(ui, server)

Module, Not App

modFrames is a module package, not a standalone application. It requires:

• Parent app infrastructure from appPlatform
• Reactive data context with artist/artwork UUIDs
• Frame analytics data from {artutils} (frame_stats with 21 columns)

For standalone testing during development, use inst/app/app.R.

Ecosystem Position

appPlatform (main Shiny app)
    |
modFrames, modGallery, modBrowse, ... (Shiny modules)
    |
artutils (data access layer)
    |
artcore (infrastructure: DB, CDN)

Reactive Data Structure

The r parameter passed to modFramesServer() must contain:

r <- reactiveValues(
  appdata = list(
    artwork = list(
      stats = list(artist_uuid = "...", art_uuid = "..."),
      frame_stats = data.table(...)  # 21 columns
    ),
    config = list(n_frames = 150)
  )
)

The frame_stats data.table is populated by artutils::get_frame_analytics() and contains:

Category	Columns
Identifiers	art_uuid, artist_uuid, frame
Temporal	elapsed_minutes, elapsed_hours, cumulative_strokes, estimated_bpm
Color	unique_colors, total_pixels, dominant_hex, dominant_pixels, color_diversity, avg_red, avg_green, avg_blue
Delta	colors_added, colors_removed, pixels_added, palette_change_score
Phase	technique_phase
Metadata	created_utc

Environment Variables

modFrames inherits environment variables from its dependencies:

Database (via {artcore}): - ART_PGHOST - PostgreSQL host - ART_PGPORT - PostgreSQL port (default: 5432) - ART_PGUSER - Database user - ART_PGPASS - Database password

CDN (via {artcore}): - ART_BUCKETS_KEY_ID - DigitalOcean Spaces key ID - ART_BUCKETS_KEY_SECRET - Spaces secret key

Documentation

• Get Started
• Integration Guide
• Architecture
• Storytelling Engine
• Function Reference

Key Functions

Function	Purpose
modFramesUI()	Main module UI
modFramesServer()	Main module server
playTimelapseUI/Server()	Timelapse playback sub-module
compareFramesUI/Server()	Frame comparison sub-module
generateJourneyInsights()	Generate storytelling narratives
plotCreativeJourney()	Create Plotly visualization

Development

# Install dev dependencies
pak::pkg_install("devtools")

# Run standalone test app
shiny::runApp("inst/app")

# Build and check
devtools::document()
devtools::check()
pkgdown::build_site()

License

Proprietary. See LICENSE for details.