weft は何をしますか?
あらゆる画像が、紙の地の上に短い色付きバーが並んだ行として再描画されます。各行はジッターされたセルに分割されます。セルはその場所の画像に最も近いパレット色を取得し、場合によっては2番目に近い色でディザリングされます。バーは強い領域では全幅、淡い領域では細くなり、エッジが通るセルは細いストライプに分割されます。何かが動くと、行は大きなブロックにステップアップし、セルは1秒間に何度も再分割されます。静止すると、ブロックは再び細かいディテールへとステップダウンします。この遷移こそがこのルックの特徴です。守ってください。
無地または透明な背景から切り抜かれた被写体には、シルエットから滑らかな深度ドームが生成されるため、伸縮することなく回転(ヨー)および傾斜(ピッチ)できます。ポイントは深度によって横方向にスライドし、光がドーム全体を転がります。フルフレームの画像には、代わりに緩やかな中央ドームが適用されます。被写体は自動的にフレームの中央に保たれます。
ファイル
| パス | 内容 |
|---|---|
src/weft.ts | エンジン。厳密に型付けされた単一のTypeScriptモジュールで、実行時依存関係はありません。createWeft(canvas, options)、enableDrop、PALETTES、および型WeftOptions、WeftConfig、Weftを提供します。 |
demo/ | カーソルに追従して回転するポートレート。パレットとバー方向のトグル、ウェブカム、ドラッグ&ドロップ、URLパラメータを備えています(Vite)。 |
references/options.md | すべてのオプションとその機能、推奨範囲。 |
references/recipes.md | 統合例:React、ヒーロー、ホバーカード、スクロール、スライドショー、リビール、ウェブカム、およびリファレンスへの一致。 |
references/pitfalls.md | この構築で発生した問題とその回避方法。 |
ワークフロー
- ソースと用途を特定する。 それは何ですか?静止画、動画、ウェブカム、それともページが既に描画しているキャンバスですか?どこに配置しますか?ヒーロー、カード、フルページ?どのような動きを求めていますか?カーソル操作、アイドルドリフト、リビール、画像間の遷移?
src/weft.tsをプロジェクトにコピーし、ファイル全体をそのまま保持します。必要なのはバンドラーまたはtscのみで、どちらもどのTSプロジェクトにもあります。プレーンJSのページの場合は、npx tscまたはesbuildで一度コンパイルしてください。demo/main.tsから始め、以下の決定事項を使用してオプションを設定します。- まず静止画を1つ表示します。
?freeze=0&yaw=-20&pitch=8&break=0でポーズを固定し、その周りにさらに構築する前に確認します。正面、両方向の回転、傾斜、および分解フレーム(break=1)をチェックします。ユーザーがリファレンスを提供した場合は、静止画をリファレンスのフレームと並べて、パレット、行の高さ、紙の色を比較します。 - 次にモーション。 実際の遷移を確認します。分解はほんの一瞬で発生するため、一目で判断せず、スクリーン録画をフレームごとにステップ実行します。次の3つを確認します。移動時には分解がはっきりと見えること、すべての静止時に完全にシャープに解像されること、回転の限界で何も伸びていないこと。
決定事項
被写体(subject.mode):
'auto'(デフォルト)を使用します。透明PNGには'alpha'を使用します。フレームの境界線がほぼ1色の場合は'backdrop'を使用します。これは境界線から背景をフラッドフィルし、グラデーションを追跡し、飛び散った斑点を除去します。その他はすべて'none'を使用します。- 風景、アートワーク、スクリーンショットの場合は強制的に
'none'にします。クリーム色の空や紙の境界線が切り取られないようにするためです。 - 背景が複雑で被写体に漏れ出る場合は、
subject.tolerance(デフォルト0.16)を調整するか、または切り抜きPNGを渡すことをお勧めします。
パレット(palette):
- プリセットから選択:
ember(暖色系のリソグラフ、肌色に最適)、graphite、riso、tide、candy、night(暗い地に明るいバー)、phosphor、またはsource(画像独自の色、ポスタライズ)。 - 独自の16進数カラー(最大16色)と
paperを渡すこともできます。 - 色は最近傍法でマッチングされます。画像が必要とする各色相ファミリーに、暗い色、中間色、明るい色を1つずつ含めてください。そうしないと、顔が平坦または濁って見えます。
- 暗い
paperでは、明るい領域のバーが自動的に広がります。
方向: 'rows'(水平、クラシックなルック)または'columns'を使用します。
フレーミング: focus: 'subject'(デフォルト)は、切り抜かれた被写体のバウンディングボックスを中央に配置します。被写体がフレームで切り取られていない軸に沿ってのみシフトします。'frame'を使用すると、写真の構図をそのまま維持します。
モーション(motion, turn):
pointer: trueにより、カーソルで操作できます。xが回転、yが傾斜を制御します。コーナーは楕円にクランプされるため、斜め方向で完全なヨーとピッチが同時に適用されることはありません。idleは、ポインターが静止したときの動作を決定します。'poses'はmotion.posesを通じてドリフトし、'center'は正面にゆっくり戻り、'hold'はそのままの位置を保持します。- 平面の画像の場合、
turn.yawは34°以下、turn.pitchは20°以下に保ちます。フルフレーム画像のヨーは約10〜15°が適切です。 turn.enabled: falseを使用すると、遷移のみがモーションとなるフラットなモザイクになります。
遷移:
- 回転は自動的にバーを分解します。クリック、スクロール速度、スライド変更、ビートなど、その他の操作には
weft.kick(amount)を呼び出します。 transition.introは読み込み時に粗い状態から解像され、transition.onSourceはソースが変更されたときに同じ動作を行います。rows.coarse / rows.fineは約4〜6倍に保ちます。
API一覧
import { createWeft, enableDrop, type WeftOptions } from './weft';
const weft = createWeft(canvas, {
source: 'portrait.png', // URL, <img>, <video>, <canvas>, File/Blob, または 'camera'
palette: 'ember', // または ['#1c1a27', ...]、または 'source'
direction: 'rows',
turn: { yaw: 30, pitch: 18 },
motion: { pointer: true, idle: 'poses' },
onSource: (w, h) => { stage.style.aspectRatio = `${w} / ${h}`; },
});
await weft.loaded;
weft.kick(0.8); // 今すぐ分解
weft.set({ palette: 'night' }); // ライブオプション変更、ディープマージ
weft.pose(-20, 6); // コードで操作。pose(null)で制御を戻す
weft.setSource('camera');
enableDrop(weft); // 任意の場所に画像/動画ファイルをドロップ
weft.destroy();
キャンバスはCSSボックスにフィットし、ページがレイアウトを所有します。data-weft-ui とマークされた要素は、フリーズされた静止画で非表示になります。weft.advance(dt, x, y) はシミュレートされたクロックを進め、フレーム正確なレンダリングを行います。
品質を保つルール
- 実際のピクセルを使用すること。 人物の写真やアバターを再描画、トレース、または「クリーンアップ」してフィードしないでください。エフェクト自体がスタイライゼーションです。
- 紙の色は落ち着かせること。 明るいパレットにはクリーム、ボーン、オフホワイトを。暗いパレットにはほぼ黒に少し色味を加えたものを使用します。純粋な#fffや#000は避けてください。
- 遷移には時間的なコントラストが必要です。 移動は粗い端に達するのに十分な速さである必要があり、静止は完全に解像されるのに十分な時間(約1秒以上)が必要です。
- UIはアイコンのみで控えめに: コーナーに低い不透明度で配置し、
data-weft-uiとマークします。 prefers-reduced-motionを尊重すること。 エンジンは既に静止した細かいモザイクを表示します。- コーナーとエッジをチェックすること: 完全な左、右、上、下、および斜めを確認してから完了とします。
デモの実行
npm install
npm run dev # Vite、デモが開きます
npm run typecheck # 厳格な tsc