Files
likang 1fde96c05e
CI / typecheck + test + build (push) Has been cancelled
打通vibemake
2026-11-05 16:21:37 +08:00

453 lines
18 KiB
TypeScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2026 ZiroEDA and contributors.
// Portions derived from KiCad, copyright The KiCad Developers. See NOTICE.md.
/**
* Load and place footprint 3D models in the three.js scene, replicating KiCad's
* exact placement matrix (render_3d_opengl.cpp get3dModelsFromFootprint):
*
* footprint: translate(x·s, -y·s, GetFootprintZPos(flipped)) · rotateZ(orientation)
* · [if back: rotateY(π)·rotateZ(π)] · scale(BiuTo3dUnits · IU_PER_MM)
* per model: translate(offset) · rotateZ(-rz)·rotateY(-ry)·rotateX(-rx)
* · scale(scale)
*
* KiCad's model space is millimetres (modelunit_to_3d_units_factor =
* BiuTo3dUnits · IU_PER_MM), and `(offset …)` is millimetres applied in that
* space. Each loader normalises geometry into mm exactly as KiCad's plugins
* do:
* - `.glb` (our hosted library, converted from the KiCad 10 STEP set) and
* project STEP/IGES models are native mm, loaded raw;
* - `.wrl` is authored in 0.1-inch units, scaled ×2.54 at load, unless the
* file carries its own top-level scale transform (WRL2BASE's
* "ApplyUnitConversion" rule in plugins/3d/vrml).
*
* Materials: `MODEL_3D` draws every material group through `OglSetMaterial`
* under `glColorMaterial( GL_AMBIENT_AND_DIFFUSE )` (3d_model.cpp:479-528),
* so what a model brings is its diffuse (as ambient too), its specular, its
* shininess and its transparency — the `SMATERIAL` the loader filled. The
* three.js material each loader produced is read back into that struct and
* replaced by the fixed-function material the caller hands out; an opaque
* group goes in the opaque pass, a transparent one (or any group of a model
* with `(opacity …)` below 1) in the back-to-front pass after the mask.
*
* Models load async and are cached per source; a part used many times is
* fetched once and cloned.
*/
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { VRMLLoader } from 'three/addons/loaders/VRMLLoader.js';
import type { BOARD } from '@ziroeda/pcbnew/board.js';
import type { FOOTPRINT, FP_3DMODEL } from '@ziroeda/pcbnew/footprint.js';
import { PROJECT_PCB } from '@ziroeda/pcbnew/project_pcb.js';
import { PgmOrNull } from '@ziroeda/common/pgm_base.js';
import { wxFindMount, wxMountFileSystem, wxReadFileSync } from '@ziroeda/wx/filefn.js';
import { loadCadModel } from './loadmodel.js';
import {
HostedLibraryMount,
mountHostedLibrary,
PROJECT_FILES_MOUNT,
} from './3d_cache/3d_cache.js';
export {
LoadHosted3DCatalog,
mountHostedLibrary,
PROJECT_FILES_MOUNT,
SetHosted3DCatalog,
} from './3d_cache/3d_cache.js';
import { stepFaceMaterial, type SMaterial, type Vec3 } from './gl_fixed_function.js';
const VRML_UNIT_MM = 2.54; // legacy VRML model unit = 0.1 inch (WRL2BASE)
/** The placement frame `get3dModelsFromFootprint` builds in, 3D units. */
export interface ModelFrame {
/** `BiuTo3dUnits()`. */
scale: number;
/** `GetFootprintZPos( false )` — the F.Paste top. */
zTopFront: number;
/** `GetFootprintZPos( true )` — the B.Paste bottom. */
zTopBack: number;
/** `modelunit_to_3d_units_factor = BiuTo3dUnits() · UNITS3D_TO_UNITSPCB`. */
modelUnitToWorld: number;
}
/** A file bundled with the uploaded project (VRML/STEP sources are ASCII). */
export interface ProjectFile {
name: string;
text: string;
bytes?: Uint8Array;
}
const rotZ = (r: number): THREE.Matrix4 => new THREE.Matrix4().makeRotationZ(r);
const rotY = (r: number): THREE.Matrix4 => new THREE.Matrix4().makeRotationY(r);
const rotX = (r: number): THREE.Matrix4 => new THREE.Matrix4().makeRotationX(r);
const deg = (d: number): number => (d * Math.PI) / 180;
/** KiCad placement matrix for one footprint model, in 3D units. */
export function modelMatrix(fp: FOOTPRINT, model: FP_3DMODEL, frame: ModelFrame): THREE.Matrix4 {
const flipped = fp.IsFlipped();
const pos = fp.GetPosition();
const m = new THREE.Matrix4().makeTranslation(
pos.x * frame.scale,
-pos.y * frame.scale, // KiCad flips Y into the 3D frame
flipped ? frame.zTopBack : frame.zTopFront,
);
m.multiply(rotZ(deg(fp.GetOrientation().AsDegrees())));
if (flipped) {
m.multiply(rotY(Math.PI));
m.multiply(rotZ(Math.PI));
}
m.multiply(
new THREE.Matrix4().makeScale(
frame.modelUnitToWorld,
frame.modelUnitToWorld,
frame.modelUnitToWorld,
),
);
m.multiply(
new THREE.Matrix4().makeTranslation(model.m_Offset.x, model.m_Offset.y, model.m_Offset.z),
);
m.multiply(rotZ(deg(-model.m_Rotation.z)));
m.multiply(rotY(deg(-model.m_Rotation.y)));
m.multiply(rotX(deg(-model.m_Rotation.x)));
m.multiply(new THREE.Matrix4().makeScale(model.m_Scale.x, model.m_Scale.y, model.m_Scale.z));
return m;
}
/**
* VRML unit conversion (WRL2BASE::SetApplyUnitConversion): legacy `.wrl`
* models are 0.1-inch units → ×2.54 into mm, but a file that already carries a
* top-level scale transform is self-converting and is left alone.
*/
function vrmlIntoMm(o: THREE.Object3D): THREE.Object3D {
const selfScaled = [o, ...o.children].some(
(c) => c.scale.x !== 1 || c.scale.y !== 1 || c.scale.z !== 1,
);
const wrapper = new THREE.Group();
wrapper.add(o);
if (!selfScaled) o.scale.setScalar(VRML_UNIT_MM);
return wrapper;
}
const extOf = (name: string): string => name.split('.').pop()?.toLowerCase() ?? '';
/** Library files are hosted as `.glb`; the path keeps its KiCad name. */
const hostedExt = (rel: string): string =>
rel.replace(/\.(wrl|wrz|step|stp|stpz|x3d|iges|igs)$/i, '.glb');
/** Join base URL + relative path, percent-encoding each segment (library
* models legitimately contain spaces, e.g. "M.2 M Key socket"). */
const joinUrl = (base: string, rel: string): string =>
`${base.replace(/\/+$/, '')}/${rel
.replace(/^\/+/, '')
.split('/')
.map(encodeURIComponent)
.join('/')}`;
/**
* The `SMATERIAL` a loader's three.js material stands for.
*
* Colours come back sRGB-ENCODED: KiCad's OCE loader reads a STEP colour with
* `Quantity_TOC_sRGB` and its VRML parser takes the file's numbers as they
* are, and both light those numbers raw. three.js's loaders converted them
* into its linear working space, so `getRGB( …, SRGBColorSpace )` is the
* exact inverse — it hands back the file's numbers.
*/
export function smaterialOf(m: THREE.Material): SMaterial {
const srgb = (c: THREE.Color): Vec3 => {
const t = { r: 0, g: 0, b: 0 };
c.getRGB(t, THREE.SRGBColorSpace);
return [t.r, t.g, t.b];
};
const opacity = m.transparent ? m.opacity : 1;
if (m instanceof THREE.MeshPhongMaterial) {
// VRML: `Material { diffuseColor specularColor emissiveColor shininess transparency }`
// (plugins/3d/vrml/v2/vrml2_material.cpp:285-300), shininess in VRML's 0..1.
return {
ambient: srgb(m.color),
diffuse: srgb(m.color),
specular: srgb(m.specular),
emissive: srgb(m.emissive),
shininess: m.shininess,
transparency: 1 - opacity,
};
}
// STEP (a hosted .glb, or a project file through OCCT): one colour per
// BREP face, the OCE loader's fixed specular/shininess around it.
const color =
'color' in m && m.color instanceof THREE.Color ? m.color : new THREE.Color(0.6, 0.6, 0.6);
return stepFaceMaterial(srgb(color), opacity, true);
}
export interface ComponentRenderHooks {
/**
* `OglSetMaterial( mat, opacity, aUseSelectedMaterial )` in the current
* `MATERIAL_MODE`. Both materials are built up front and parked on the
* mesh (`userData.normalMat` / `userData.selectedMat`) so a rollover or a
* cross-probed selection is a swap, not a rebuild.
*/
material: (
m: SMaterial,
opacity: number,
transparentPass: boolean,
selected: boolean,
) => THREE.Material;
/** `renderOpaqueModels` / `renderTransparentModels` slots. */
opaqueOrder: number;
transparentOrder: number;
/** `BOARD_ADAPTER::IsFootprintShown`. */
showFootprint: (fp: FOOTPRINT) => boolean;
}
/**
* Load every footprint's 3D models and add them to `parent`. `libBase` is
* where the hosted library lives (a `.glb` URL prefix); `projectFiles` carries
* the uploaded project's own files so ${KIPRJMOD}/relative references load
* exactly as KiCad loads them from the project directory.
*/
/**
* `S3D_CACHE`: a loaded model outlives the scene it was loaded for.
* `RENDER_3D_OPENGL::reload` calls `load3dModels`, which asks the cache and
* only reads files it has not seen — so a reload (an appearance toggle, a
* board edit) never re-fetches or re-tessellates. Keyed by URL for the
* hosted library and by name + size for a project file.
*/
const modelCache = new Map<string, Promise<THREE.Object3D | null>>();
export interface MountedComponents {
dispose: () => void;
/** Every model settled (loaded or failed) — `load3dModels` has returned. */
ready: Promise<void>;
}
export function mountComponents(
parent: THREE.Object3D,
board: BOARD,
frame: ModelFrame,
libBase: string,
projectFiles?: ProjectFile[],
onChange?: () => void,
/**
* `EDA_3D_VIEWER_SETTINGS::m_Render.show_model_bbox` — Preferences >
* 3D Viewer > Realtime Renderer's "Show model bounding boxes".
*
* `RENDER_3D_OPENGL::renderModel` draws each model's outer bounding box in
* green (`MakeBbox( m_model_bbox, …, { 0, 1, 0, 1 } )`, 3d_model.cpp:247).
*/
showModelBbox?: boolean,
/**
* `load3dModels( REPORTER* aStatusReporter )`: "Loading %s..." with the
* short file name of each model as it is fetched (create_scene.cpp:1656-
* 1662). Upstream loads one file at a time, so the field names the one in
* hand; here the fetches overlap, so the field names one still in flight
* and moves on as each lands.
*/
report?: (text: string) => void,
hooks?: ComponentRenderHooks,
): MountedComponents {
const vrmlLoader = new VRMLLoader();
const gltfLoader = new GLTFLoader();
const cache = modelCache;
// Private files never share name-based entries between projects or reloads.
// The CAD tessellator's persistent cache remains keyed by the actual bytes.
const privateCache = new Map<string, Promise<THREE.Object3D | null>>();
const added: THREE.Object3D[] = [];
const pendingLoads: Promise<unknown>[] = [];
const disposables: { dispose(): void }[] = [];
let cancelled = false;
const enc = new TextEncoder();
// The project's files where KiCad would find them, for as long as this scene
// lives; the library where the install puts it.
mountHostedLibrary();
const prj = PgmOrNull()?.GetSettingsManager().Prj();
const projectDir = prj?.GetProjectPath() ?? '';
const projectMount = new PROJECT_FILES_MOUNT(new Set(projectFiles?.map((f) => f.name) ?? []));
const unmountProject =
projectFiles && projectDir.startsWith('/') ? wxMountFileSystem(projectDir, projectMount) : null;
const resolver = PROJECT_PCB.Get3DFilenameResolver();
// wxFileName( fp_model.m_Filename ).GetFullName(): the name and extension
const inFlight = new Set<string>();
const reportInFlight = (): void => {
const next = inFlight.values().next();
if (!next.done) report?.(`Loading ${next.value}...`);
};
const loadUrl = (url: string): Promise<THREE.Object3D | null> =>
/\.glb$/i.test(url)
? gltfLoader
.loadAsync(url)
.then((g) => g.scene as THREE.Object3D)
.catch(() => null)
: vrmlLoader
.loadAsync(url)
.then((o) => vrmlIntoMm(o))
.catch(() => null);
// Dispatch a project file by extension, mirroring KiCad's 3d plugin registry
// (vrml plugin for .wrl, the OCC kernel for STEP/IGES). Compressed variants
// (.wrz/.stpz) and .x3d are not loadable from text-ingested projects yet.
const loadProjectFile = (name: string): Promise<THREE.Object3D | null> => {
const file = projectFiles?.find((f) => f.name === name);
if (!file) return Promise.resolve(null);
switch (extOf(name)) {
case 'wrl':
return Promise.resolve().then(() => {
try {
return vrmlIntoMm(
vrmlLoader.parse(
file.bytes ? new TextDecoder().decode(file.bytes) : file.text,
name,
) as THREE.Object3D,
);
} catch {
return null;
}
});
case 'step':
case 'stp':
return loadCadModel(file.bytes ?? enc.encode(file.text), 'step');
case 'iges':
case 'igs':
return loadCadModel(file.bytes ?? enc.encode(file.text), 'iges');
default:
return Promise.resolve(null);
}
};
// A file read by path (an embedded model in the temp directory): the same
// plugin dispatch, from bytes.
const loadBytes = (path: string, bytes: Uint8Array): Promise<THREE.Object3D | null> => {
switch (extOf(path)) {
case 'wrl':
return Promise.resolve().then(() => {
try {
const text = new TextDecoder().decode(bytes);
return vrmlIntoMm(vrmlLoader.parse(text, path) as THREE.Object3D);
} catch {
return null;
}
});
case 'step':
case 'stp':
return loadCadModel(bytes, 'step');
case 'iges':
case 'igs':
return loadCadModel(bytes, 'iges');
default:
return Promise.resolve(null);
}
};
board.Footprints().forEach((fp, fpIndex) => {
if (hooks && !hooks.showFootprint(fp)) return;
for (const model of fp.Models()) {
if (!model.m_Show || !model.m_Filename) continue;
// "Loading %s..." for every shown model, before it is resolved (create_scene.cpp:1663-
// 1670): one that is not found is named too.
const fullName = model.m_Filename.slice(model.m_Filename.lastIndexOf('/') + 1);
report?.(`Loading ${fullName}...`);
// S3D_CACHE::load -> ResolvePath( aModelFile, aBasePath, aEmbeddedFilesStack ).
// The footprint's library path is not known here; nor are embedded files
// (the plain board view does not carry them).
const full = resolver.ResolvePath(model.m_Filename, '', []);
if (full === '') continue;
const where = wxFindMount(full);
if (!where) continue;
let key: string;
let load: () => Promise<THREE.Object3D | null>;
if (where.mount === HostedLibraryMount()) {
const url = joinUrl(libBase, hostedExt(where.rel));
key = url;
load = () => loadUrl(url);
} else if (where.mount === projectMount) {
const name = where.rel;
key = `project:${name}:${projectFiles?.find((f) => f.name === name)?.text.length ?? 0}`;
load = () => loadProjectFile(name);
} else {
// An embedded file written to the temp directory (GetTemporaryFileName).
const bytes = wxReadFileSync(full);
if (!bytes) continue;
key = `file:${full}`;
load = () => loadBytes(full, bytes);
}
const selectedCache = where.mount === HostedLibraryMount() ? cache : privateCache;
let p = selectedCache.get(key);
if (!p) {
p = load();
selectedCache.set(key, p);
inFlight.add(fullName);
void p.finally(() => {
inFlight.delete(fullName);
reportInFlight();
});
}
pendingLoads.push(p);
const matrix = modelMatrix(fp, model, frame);
// `sM.m_Opacity`: 1 keeps the model in the opaque pass
const opacity = model.m_Opacity;
const opaque = opacity >= 1;
void p.then((obj) => {
if (cancelled || !obj) return;
const inst = obj.clone();
inst.matrixAutoUpdate = false;
inst.matrix.copy(matrix);
inst.matrixWorldNeedsUpdate = true;
// the BOARD_ITEM a ray-hit on this model reports (addModels' aBoardItem)
inst.userData.footprint = fpIndex;
if (hooks) {
inst.traverse((child) => {
if (!(child instanceof THREE.Mesh)) return;
const src = child.material as THREE.Material;
const sm = smaterialOf(src);
// MODEL_3D::Draw: a material with transparency goes to the
// transparent pass; a model with opacity < 1 goes there whole.
const transparentPass = !opaque || sm.transparency > 1.1920929e-7;
const op = transparentPass ? opacity : 1;
const mat = hooks.material(sm, op, transparentPass, false);
const sel = hooks.material(sm, op, transparentPass, true);
// glEnable( GL_CULL_FACE ) throughout — but a VRML file's winding
// is its own affair (`solid`/`ccw`), and three.js's loader keeps
// it two-sided; STEP faces come oriented.
if (src.side === THREE.DoubleSide) {
mat.side = THREE.DoubleSide;
sel.side = THREE.DoubleSide;
}
child.material = mat;
child.userData.normalMat = mat;
child.userData.selectedMat = sel;
child.renderOrder = transparentPass ? hooks.transparentOrder : hooks.opaqueOrder;
disposables.push(mat, sel);
});
} else if (opacity < 1) {
inst.traverse((child) => {
if (child instanceof THREE.Mesh) {
const m = (child.material as THREE.Material).clone();
m.transparent = true;
m.opacity *= opacity;
child.material = m;
}
});
}
parent.add(inst);
added.push(inst);
if (showModelBbox) {
const helper = new THREE.Box3Helper(new THREE.Box3().setFromObject(inst), 0x00ff00);
parent.add(helper);
added.push(helper);
}
onChange?.();
});
}
});
return {
dispose: () => {
cancelled = true;
unmountProject?.();
for (const o of added) parent.remove(o);
for (const d of disposables) d.dispose();
},
ready: Promise.allSettled(pendingLoads).then(() => undefined),
};
}