# samyost1/3dicon architecture

> Architecture diagram of the GitHub repository samyost1/3dicon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samyost1/3dicon
- Repository: https://github.com/samyost1/3dicon

## Overview

3dicon is a prompt-driven tool for creating looping 3D icons with transparent animation. Its workflow generates a still, pauses for human review, composes and approves motion, renders a loop, removes the chosen backing color frame by frame, then normalizes and encodes the result. The CLI coordinates these paid and time-consuming stages; verification reports catch motion, seam, and alpha issues. The README documents multiple image and video backends plus WebM and flat MP4 exports. Some CLI wiring is inferred from the sampled excerpts and README, so uncertain links are omitted.

Main entry points: [`skills/3dicon/iconloop/cli.py`](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/cli.py) (CLI workflow), [`skills/3dicon/iconloop/kling.py`](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/kling.py) (Video rendering), [`skills/3dicon/iconloop/providers.py`](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/providers.py) (Still image generation), [`skills/3dicon/iconloop/encode.py`](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/encode.py) (Animation encoding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creation["Prompt and Motion"]
  node_cli["CLI workflow<br/>[cli.py]"]
  node_motion["Motion composer<br/>[motion.py]"]
end

subgraph group_render["Image and Video Generation"]
  node_still["Still image generation<br/>[providers.py]"]
  node_image_backends["Image model APIs"]
  node_video["Video rendering<br/>[kling.py]"]
  node_openrouter_video["OpenRouter video API"]
  node_replicate["Replicate API"]
  node_backing["Backing composite<br/>[kling.py]"]
end

subgraph group_processing["Transparency and Export"]
  node_frame_extract["Frame extraction<br/>[matte.py]"]
  node_matting["Alpha matting<br/>[matte.py]"]
  node_matting_model["Matting model"]
  node_normalize["Framing normalization<br/>[matte.py]"]
  node_encode["Animation encoding<br/>[encode.py]"]
  node_verify["Output verification<br/>[verify.py]"]
end

subgraph group_support["Runtime Support"]
  node_http["HTTP helpers<br/>[http.py]"]
  node_config["Key configuration<br/>[config.py]"]
end

node_user(("User"))
node_reviewer(("Human reviewer"))
node_artifacts["Icon outputs"]
node_ffmpeg["ffmpeg"]

node_user -->|"requests icon"| node_cli
node_cli -->|"generates still"| node_still
node_cli -->|"presents still"| node_reviewer
node_reviewer -->|"approves stage"| node_cli
node_cli -->|"composes motion"| node_motion
node_cli -->|"starts render"| node_video
node_video -->|"composites still"| node_backing
node_cli -->|"prepares image"| node_backing
node_video -.->|"submits video job"| node_openrouter_video
node_video -.->|"submits video job"| node_replicate
node_still -.->|"requests image"| node_image_backends
node_still -->|"sends requests"| node_http
node_video -->|"sends requests"| node_http
node_still -->|"reads keys"| node_config
node_video -->|"reads keys"| node_config
node_cli -->|"loads settings"| node_config
node_cli -->|"extracts render"| node_frame_extract
node_frame_extract -->|"decodes frames"| node_ffmpeg
node_cli -->|"mattes frames"| node_matting
node_matting -->|"estimates alpha"| node_matting_model
node_cli -->|"normalizes frames"| node_normalize
node_cli -->|"encodes formats"| node_encode
node_encode -->|"encodes video"| node_ffmpeg
node_cli -->|"checks outputs"| node_verify
node_cli -->|"writes work files"| node_artifacts
node_encode -->|"writes animations"| node_artifacts
node_verify -->|"reads outputs"| node_artifacts
node_reviewer -->|"reviews still"| node_artifacts

click node_cli "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/cli.py"
click node_motion "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/motion.py"
click node_still "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/providers.py"
click node_video "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/kling.py"
click node_backing "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/kling.py"
click node_frame_extract "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/matte.py"
click node_matting "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/matte.py"
click node_normalize "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/matte.py"
click node_encode "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/encode.py"
click node_verify "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/verify.py"
click node_http "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/http.py"
click node_config "https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_motion,node_user,node_reviewer toneBlue
class node_still,node_image_backends,node_video,node_openrouter_video,node_replicate,node_backing toneAmber
class node_frame_extract,node_matting,node_matting_model,node_normalize,node_encode,node_verify toneMint
class node_http,node_config toneRose
class node_artifacts,node_ffmpeg toneIndigo
```

## Components

### Prompt and Motion

- [CLI workflow](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/cli.py): `skills/3dicon/iconloop/cli.py`
- [Motion composer](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/motion.py): `skills/3dicon/iconloop/motion.py`

### Image and Video Generation

- [Still image generation](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/providers.py): `skills/3dicon/iconloop/providers.py`
- **Image model APIs**
- [Video rendering](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/kling.py): `skills/3dicon/iconloop/kling.py`
- **OpenRouter video API**
- **Replicate API**
- [Backing composite](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/kling.py): `skills/3dicon/iconloop/kling.py`

### Transparency and Export

- [Frame extraction](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/matte.py): `skills/3dicon/iconloop/matte.py`
- [Alpha matting](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/matte.py): `skills/3dicon/iconloop/matte.py`
- **Matting model**
- [Framing normalization](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/matte.py): `skills/3dicon/iconloop/matte.py`
- [Animation encoding](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/encode.py): `skills/3dicon/iconloop/encode.py`
- [Output verification](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/verify.py): `skills/3dicon/iconloop/verify.py`

### Runtime Support

- [HTTP helpers](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/http.py): `skills/3dicon/iconloop/http.py`
- [Key configuration](https://github.com/samyost1/3dicon/blob/main/skills/3dicon/iconloop/config.py): `skills/3dicon/iconloop/config.py`

### Other components

- **User**
- **Human reviewer**
- **Icon outputs**
- **ffmpeg**

## Connections

- User → CLI workflow: requests icon
- CLI workflow → Still image generation: generates still
- CLI workflow → Human reviewer: presents still
- Human reviewer → CLI workflow: approves stage
- CLI workflow → Motion composer: composes motion
- CLI workflow → Video rendering: starts render
- Video rendering → Backing composite: composites still
- CLI workflow → Backing composite: prepares image
- Video rendering → OpenRouter video API: submits video job
- Video rendering → Replicate API: submits video job
- Still image generation → Image model APIs: requests image
- Still image generation → HTTP helpers: sends requests
- Video rendering → HTTP helpers: sends requests
- Still image generation → Key configuration: reads keys
- Video rendering → Key configuration: reads keys
- CLI workflow → Key configuration: loads settings
- CLI workflow → Frame extraction: extracts render
- Frame extraction → ffmpeg: decodes frames
- CLI workflow → Alpha matting: mattes frames
- Alpha matting → Matting model: estimates alpha
- CLI workflow → Framing normalization: normalizes frames
- CLI workflow → Animation encoding: encodes formats
- Animation encoding → ffmpeg: encodes video
- CLI workflow → Output verification: checks outputs
- CLI workflow → Icon outputs: writes work files
- Animation encoding → Icon outputs: writes animations
- Output verification → Icon outputs: reads outputs
- Human reviewer → Icon outputs: reviews still