|
Download README.md from Pine532/chameleon-layout-generator: direct link, hf CLI and curl.
- Browser
- Download file 10.6 kB
-
https://huggingface.co/Pine532/chameleon-layout-generator/resolve/main/README.md
- Command line
-
hf download hf://Pine532/chameleon-layout-generator/README.md
-
curl -L -o README.md https://huggingface.co/Pine532/chameleon-layout-generator/resolve/main/README.md
10.6 kB
| license: apache-2.0 | |
| library_name: numpy | |
| pipeline_tag: other | |
| tags: | |
| - layout | |
| - design | |
| - banner-resizing | |
| - regression | |
| - mlp | |
| - hackathon | |
| # Chameleon learned layout generator | |
| A 6,600-weight MLP that, given the analysed layout of a design and a target canvas size, predicts the box each content unit | |
| should occupy on the target. The Chameleon resize engine turns the prediction into extra candidate layouts (`learned`, | |
| `learned:<rung>`); the engine's text fitting, hard checks, rule score and critic then judge them like every other candidate. It | |
| runs on numpy alone, offline, in well under a millisecond per task. Trained on layouts made by human designers (Crello / VistaCreate | |
| size variants), geometry only. | |
| > **Status: judged (round 6) and shipped behind an admission guard.** It beats the uniform stretch clearly on held-out design | |
| > families and moves the engine's picks closer to what designers made, but a strong vision judge preferred its changed picks only 66 | |
| > to 44 (small text on narrow canvases, top-heavy stacks on tall ones). With the guard (a learned layout ships only if it keeps the | |
| > smallest text within 1 px and the utilization score within 0.05 of the pick made without it) the kept picks were judged 54 to 17, | |
| > and 71 to 27 out of sample on 90 fresh designs (round 7; the reverted picks 15 to 28). | |
| > Evidence, numbers and caveats: `layout_report.md` §4 to §6c; every changed pick: `layout_picks.md`. | |
| > **Licence.** Apache-2.0 (confirmed by the team on 2026-10-28). The weights derive from the geometry of Crello / VistaCreate | |
| > templates (dataset licence CDLA-Permissive-2.0; no pixels, text, fonts or colours were used or are included). | |
| ## Model details | |
| * **Type.** Multi-layer perceptron, 33 inputs, two hidden layers of 64 `tanh` units, 4 outputs. The output is a correction added to | |
| the source box (the uniform stretch): `box = src_box + net(standardise(features))`, in shares of the target canvas | |
| (cx, cy, w, h). | |
| * **Developed by.** Dev 3, Chameleon hackathon team (2026-10-27). **Framework.** numpy for training (a hand-written Adam loop) and | |
| inference. | |
| * **Size.** 31.3 KB (`engine/models/layout.npz`, float32); 6,596 weights. Limit 200 KB. | |
| * **File.** `layout.npz`: `kind` ("mlp"), `activation` ("tanh"), `n_layers` (3), `feature_names` (33 strings, checked against | |
| `engine.resize.LAYOUT_FEATURES` at load), `mu` and `sd` (input standardisation), `w0..w2` and `b0..b2`, `trained_on` (a note). | |
| Arrays and strings only; loads with `allow_pickle=False`. | |
| * **Loader.** `engine.resize._layout_model()` (lazy, cached per file state); a missing, corrupt or inconsistent file means the | |
| family is not generated and the engine's output is byte-identical to the output without it. `CHAMELEON_LEARNED=0` switches it off. | |
| ## Intended use | |
| Inside the engine only: `_learned_candidates` (end of section 2 of `engine/resize.py`). For every free content unit (not corner | |
| furniture, header/footer band or rotated side label) it supplies where the unit's centre goes and how big its box is; text takes | |
| the predicted width and the largest whole font size whose wrapped text fits the predicted box (never below what the proportional | |
| family gives, never above the anchor's cap), images, groups and rotated elements are fitted into the box keeping their aspect. | |
| Floors, margins, collisions, decorations and everything else are the engine's. It never moves, adds or removes an element by | |
| itself and never touches content or fonts. The engine also picks without the family and lets a learned layout replace that pick only | |
| when its smallest text is within `TUNABLES["learned"]["guard_px"]` (1 px) and its utilization score within `guard_util` (0.05) of it. | |
| **Out of scope.** Aspect changes under 3% (not generated; the model also does not beat the stretch below an aspect change of 0.2), | |
| designs far from poster / social / banner layouts, scoring or ranking layouts, any claim about what a human or the organizers' | |
| judge prefers (see Limitations). | |
| ## Inputs and output | |
| Per content unit, 33 numbers from `engine.resize._layout_features(analysis, target)` (the same function builds the training set): | |
| the unit's source box and ink box as shares of the source canvas (8), kind flags (text, image, shape, pinned corner furniture, | |
| band, rotated, multi-element group), prominence, largest font size over the source short side, log text length, block index, block | |
| count and relative position, flow axis, number of content units, source / target / log-ratio aspect (natural logs), source and target | |
| short sides over 1000, rank by area and by font size, alignment (left / right) and a sibling flag. Geometry and text length only: | |
| nothing reads ids, asset names, text, fonts or exact canvas sizes (a rename test covers it). Output: the correction to | |
| (cx, cy, w, h) of the source box. | |
| ## Training data | |
| `cyberagent/crello` v5.1 (VistaCreate designs), geometry only (`tools/crello/extract_layouts.py`). 18,449 usable size-variant pairs | |
| (same element count, type sequence and text lengths; `pairs.py`) in 1,316 families, each read in both directions: 36,898 directed | |
| pairs, 240,227 content-unit rows, 5,563 source templates, no pair dropped after the pair filters. Source templates are converted | |
| into Chameleon tasks (grey boxes for vector art, missing images, synthetic words of the real length) and analysed with the engine's | |
| `analyze_source`; the target of a unit is the union of the designer's boxes of its member elements at the other size. Families are | |
| split 70 / 30 (915 train, 401 test) by a hash of the family, so no template family is on both sides. The shipped weights were trained | |
| on 85% of the train families (127,554 rows, both directions), early-stopped on the other 15% (33,443 rows); the 401 test families | |
| were never trained on or selected with. Rows are weighted by 1 / sqrt(pairs in the family). | |
| Loss: the engine's own designer distance on unit boxes, `hypot(dcx, dcy) + 0.5 (|dw| + |dh|)` (smoothed), 40 epochs of Adam | |
| (learning rate 2e-3, cosine decay, batch 1,024, weight decay 1e-5), 5 seeds, the best on validation shipped. | |
| ## Evaluation | |
| On the 6,412 held-out pairs (39,620 unit rows, 401 families), distance to the designer layout (lower is better): | |
| | | unit distance | element distance (pairs pooled / family-balanced) | MAE cx / cy / w / h | | |
| |---|---|---|---| | |
| | uniform stretch | 0.1886 | 0.1905 / 0.1260 | 0.068 / 0.066 / 0.103 / 0.059 | | |
| | ridge regression | 0.1828 | 0.1822 / 0.1365 | 0.074 / 0.069 / 0.082 / 0.057 | | |
| | sklearn MLP, squared loss | 0.1976 | 0.1993 / 0.1612 | 0.091 / 0.077 / 0.076 / 0.053 | | |
| | **this model** | **0.1525** (5 seeds: 0.1524 ± 0.0004) | **0.1545 / 0.1081** | 0.063 / 0.061 / 0.062 / 0.043 | | |
| It beats the stretch in 67% of held-out pairs (35% when the aspect changes by under 0.2, 71% from 0.2 to 0.7, 84% above 0.7). In the | |
| engine (3,000 pairs, 1,008 in test families; `layout_eval.py`): a `learned` candidate exists in 94% of test pairs, is valid in 96% | |
| of those, is the valid candidate closest to the designer in 53%, and the selector ships it in 29%; pick distance 0.2522 → 0.2352 | |
| (gain +0.0169, family-bootstrap 95% interval [+0.0132, +0.0209]; train families +0.0162). On our own sets (samples 46, synthetic 271, | |
| holdout 845 pairs) hard checks, fallbacks and all-text-at-floor counts are unchanged and 136 picks move to `learned` (text smaller in | |
| 43, larger in 8). A strong vision judge, shown each of those changed picks against the engine's own (both letter orders), preferred the | |
| learned pick 66 to 44 (110 decided). With the admission guard, as shipped: picked in 23.5% of test pairs, pick distance 0.2522 → 0.2429 | |
| (+0.0093 [+0.0062, +0.0127]), the changed picks' smallest text larger in 392 and smaller in 36 of 699; on our three sets 97 picks change | |
| (smaller text in 15, larger in 7), judged 54 to 17; on 90 fresh designs (1,900 pairs) 117 picks change, judged 71 to 27. Full tables, | |
| the exploration (features, sizes, losses), both judge rounds and visual notes: `layout_report.md`. | |
| ## Limitations and risks | |
| * **Designers are not the judge.** Distance to the designer rewards what designers did: text kept near the area-preserving size, | |
| sparse canvases, content bleeding at the edges. The earlier judge rounds asked for larger text and filled canvases; the model | |
| inherits the designers' habits (top-heavy stacks on taller targets, small labels), and the rule score's fidelity term likes them. | |
| Visual review: tiny text at 160 x 600 and 728 x 90, a crowded 16:9 collage, a half-empty square stack among the changes. | |
| * **Different distribution.** Crello is VistaCreate social posts, flyers and banners with grey placeholder art and synthetic text; | |
| the organizers' briefs are brand banners with real photos, logos and copy. Nothing here has been checked on a held-out brief. | |
| * **The guard's thresholds were chosen on round 6 and checked out of sample in round 7** (90 fresh designs, 168 comparisons): kept | |
| picks 71 to 27, reverted 15 to 28. The utilization axis replicated; the text axis alone did not (7 to 6). | |
| * **The critic never saw these layouts.** 10 of the 136 unguarded changed picks are the judge-distilled critic choosing a learned | |
| finalist (judged 6 to 4); the 8 other picks its finalist set moved revert through the guard. | |
| * **Validity.** 95% of generated candidates pass every hard check; the rest are last-resort layouts with text overlapping text | |
| (never shipped: the selector only takes valid ones). At large aspect changes (>= 0.7) 91%. | |
| * **Local measurements only** (macOS CoreText text measurement); the Docker (FreeType) run was not repeated for this model. | |
| * **Trained on the train families only** so that the held-out numbers are honest; retraining on all 1,316 families | |
| (`train_layout.py`) would add about 30% more data and cannot be evaluated on Crello afterwards. | |
| ## Reproduce | |
| ```bash | |
| .venv/bin/python tools/crello/layout_dataset.py # 5 s | |
| OMP_NUM_THREADS=4 /opt/anaconda3/bin/python3 tools/crello/train_layout.py --skip-sklearn --export engine/models/layout.npz # ~2.5 min | |
| .venv/bin/python tools/crello/designer_eval.py --out output/crello/eval_learned # ~1.5 min on 8 workers | |
| .venv/bin/python tools/crello/layout_eval.py --base output/crello/eval_base/candidates.jsonl --new output/crello/eval_learned/candidates.jsonl | |
| .venv/bin/python -m unittest tests.test_learned | |
| ``` | |
| Standalone forward pass (no engine): standardise the 33 features with `mu` and `sd`, apply `tanh(x @ w0 + b0)`, `tanh(. @ w1 + b1)`, | |
| `. @ w2 + b2`, add the result to the first four features (the source box as cx, cy, w, h shares). | |