TutorialLineales · 1D listones, perfiles y varillas

Tutorial paso a paso del módulo Lineales de Despiece: el toggle de activación en Configuración → Lineales, los defaults del taller (kerf, espesor de disco, perfil y material), el editor de keywords para auto-detectar cortes a partir de los nombres del CAD, el panel [L] con sus vistas Stock | Catálogo, el wizard + Listón, el importador CSV bilingüe (Despiece + OptiCut), el packer FFD 1D con multi-restart y la integración con BOM · Pedido · Etiquetas.

Las lineales son piezas 1D (no tableros 2D): listones de madera maciza, machimbres, perfiles de aluminio, zócalos PVC, varillas de placard Ø25/30, tirantes, alfajías y tapacantos. Se cortan de barras nominales del catálogo y se empacan con un bin-packer FFD + multi-restart (primer ajuste decreciente con 32 variantes semilladas). El módulo está desactivado por default para no pagar el costo del UI extra en apps que sólo trabajan con tableros crudos. La activación se persiste en state.settings.linealesEnabled y sobrevive a .despiece recargados: los datos lineales se guardan como soft fields (linearItems, linearResult) y se recuperan al reactivar. El modelo de ejemplo es CocinaV9.despiece.

1 · Activar el módulo Lineales

El módulo vive detrás de un toggle global porque las apps que sólo trabajan con tableros crudos no necesitan el UI extra. La activación se hace una sola vez por taller.

Configuración (icono engranaje de la topbar) → tab Listones (cortado 1D) (id lineal, registrado en src/ui/settings-panel/tabs.ts:26). El primer row, Activar módulo Lineales (#stg-lineales-enabled, persistido vía setSettings({ linealesEnabled }) desde src/ui/settings-panel/lineal-wiring.ts:34) prende o apaga todo lo demás.

Cuando el toggle está apagado:

Esto significa que podés apagar el módulo para limpiar la UI sin perder trabajo: las marcas quedan en el .despiece y se reactivan al volver a prender.

2 · Settings → Lineales · defaults del taller

El tab tiene cuatro inputs numéricos / texto que aplican tanto al wizard + Listón como al botón Calcular barras (FFP) y al botón Auto-detectar del modelo. Todos se persisten en localStorage[despiece.lineales.defaults.v1] y se sanitizan con sanitizeLinearDefaults() (cae a per-field default si el valor está corrupto, nunca tira):

El packer hardcodea allowRotate: false (DEFAULT_LINEAL_DEFAULTS y types.ts:125). Las lineales no rotan: el corte siempre se mide sobre el largo nominal de la barra (spec.lengthMm). Esto es por dominio — una varilla de placard Ø25 sigue siendo Ø25 en cualquier posición, pero el packer no intenta cortar transversal.

3 · Auto-detección por nombre (keywords)

El botón Auto-detectar del modelo del panel [L] usa un diccionario de palabras clave para proponer piezas como lineales a partir del nombre del CAD (sin mutar el modelo — solo agrega items a state.project.linearItems). La regla es longest-keyword-wins: si un part se llama Estante listonado reforzado, matchea listonado (9 chars) por encima de listón (6) o estante (7).

El editor (#stg-lineales-keywords-list) tiene tres filas:

El matcher (matchLinealKeyword en src/lineales/auto-lineales.ts:38) combina folding de acentos (Listón → liston) con token-AND para multi-token: si el keyword es tirante pine, todos sus tokens tienen que aparecer como tokens del nombre (en cualquier orden).

Keywords built-in (src/lineales/types.ts:168):

Cada keyword tiene también aliases localizados en aliasesByLocale (es-AR, en-US, pt-BR, fr-FR, de-DE, it-IT) para que varilla matchee también closet rod / cabideiro / tringle penderie / Kleiderstange / asta armadio. El matching sigue siendo longest-key + folding; los aliases viven en los perfiles, no en las keywords.

4 · Catálogo built-in (vista Catálogo del panel)

El panel [L] tiene una vista Catálogo (segmented al lado de Stock) que muestra los perfiles disponibles en modo read-only. La edición se hace en Configuración → Materiales (customs) o desde el catálogo lineal (src/lineales/stock-store.ts).

Los 11 perfiles built-in viven en src/lineales/types.ts:136-146:

Los built-ins son inamovibles — viven en el código, no en localStorage. Si necesitás un perfil custom (ej. Pino tratado 2×4″), agregalo vía addLinealProfile desde el panel de stock catalogado (cap 200 customs en stock-store.ts:13).

5 · Abrir el panel [L] (Shift+L)

Cargar un modelo CAD (cualquier STEP/IGES/BREP/glTF/GLB), pulsar Shift+L o click en el botón [L] del topbar (id #tb-lineales). El panel se abre como un sheet full-screen (min(1100px, 92vw) × 86vh) con un segmented Stock | Catálogo.

El shell vive en src/ui/lineales-panel.ts. La vista por default es Stock; el switcher es el nav.lineales-seg con dos botones .lineales-seg-btn[data-view="stock|catalogo"]. El header expone:

• title con kicker "Listones" + nombre del proyecto activo.
• meta con el contador de piezas y barras ({count} · Barras: {bars}).
• Exportar (CSV/XLSX/PDF) y la × de cerrar.

Si el módulo está apagado en Settings, el botón [L] no se renderiza y el atajo Shift+L muestra un transient:

Módulo Lineales desactivado · activalo en Settings → Lineales

6 · + Listón · wizard manual

El título del wizard es + Listón y su botón de submit (#lineales-add, etiqueta "Agregar") toma cuatro campos del #lineales-w-* form. La validación (stock-view.ts:70):

if (!profile || !Number.isFinite(length) || length <= 0
    || !Number.isFinite(qty) || qty <= 0) return;

Al click Agregar se llama addLinearItem({...source: 'wizard'}) en src/state/lineales-slice.ts:22. La función genera id = uuid() si falta, valida con isLinearStockLine (defensa contra shape inválido), y bumpea linearEpoch (la vista Stock se re-renderiza vía on(state)).

Internamente el item nuevo es un LinearStockLine:

interface LinearStockLine {
  id: string;
  parentPartId?: string;
  name: string;
  profileMm: { w: number; h: number };  // snapshot del perfil
  lengthMm: number;                      // largo del corte pedido
  materialId: string;                    // snapshot del material
  qty: number;
  source: 'cad' | 'wizard' | 'csv' | 'auto-detect';
}

El item no clona el perfil — copia profileMm por valor y referencia materialId por id. Si después se renombra el material en Configuración → Materiales, materials/rewrite-refs.ts:124 reescribe el materialId en todos los lineales al cargar el proyecto (consistencia con el resto de la app).

7 · Importar CSV (Despiece-lineal y OptiCut-lineal)

El botón Importar CSV… (#lineales-import-csv) abre un picker nativo y acepta .csv / .tsv. El parser (src/lineales/parse-csv.ts) detecta dos dialectos mirando el header (case-insensitive, lowercase) y maneja BOM UTF-8:

El separador también se autodetecta (detectSep línea 37): si el header tiene ;, sep = ;, si no ,. La columna profile_mm acepta , o . como decimal y x o × como separador, vía regex ^(\d+(?:[.,]\d+)?)\s*[x×]\s*(\d+(?:[.,]\d+)?)$/i (línea 57).

Ejemplo válido (/tmp/lineales-demo.csv):

cantidad;nombre;profile_mm;largo_mm;material
4;Listón pino 2×3 refuerzo;50×75;1800;maciza_pino_fk
2;Machimbre 1×4 cielorraso;25×100;2200;maciza_machimbre
8;Varilla placard 25 closet;25×25;1200;varilla_placard

Cada fila se agrega con addLinearItem({..., source: 'csv'}). Las filas inválidas (qty ≤ 0, profile sin match, length no numérico) van a errors[] y no rompen el parse — el resto del archivo entra.

Si falta alguna columna obligatoria, el parser devuelve errors: ['Faltan columnas: cant/qty, nombre/name, profile_mm, largo_mm'] y no agrega nada. La columna material del CSV es opcional — si está vacía, el item se guarda con materialId = 'maciza_pino_fk' (fallback de pino FK para no romper el lookup downstream).

8 · Auto-detectar del modelo

El botón Auto-detectar del modelo (#lineales-auto) corre selectLinealMatches(parts, keywords) y agrega un item por cada match con source: 'auto-detect'. La pieza original del CAD no se muta — solo se crea un LinearStockLine con parentPartId: m.part.id y lengthMm = Math.round(max(profile.nominalLengthMm, 100) / 4) (un cuarto del largo nominal como heurística de corte inicial).

El cuarto de largo nominal es solo un starting point — el usuario edita el lengthMm directamente en la fila de stock. Para CocinaV9 el catálogo de nombres es estándar (puerta, estante, cajón) y el auto-detect no agrega items porque ninguno matchea las keywords.

El flag addLinearItem bumpea linearEpoch; la vista Stock se re-renderiza mostrando los items nuevos. Si la pieza ya tenía un item lineal previo (mismo parentPartId), el nuevo se acumula — no se deduplica (decisión del spec §3.13: auto-detect es sugerir, no sincronizar).

9 · Calcular barras (packer FFD 1D + multi-restart)

El botón Calcular barras (#lineales-pack) corre packLinealStock(items, spec) (src/lineales/packer.ts:164) sobre la lista actual. El algoritmo es:

1. Expand cada LinearStockLine por su qty → flat array de ExpandedCut[] (línea 147).
2. FFD inicial = sort((a,b) => b.lengthMm - a.lengthMm) — primer ajuste decreciente (línea 171).
3. Multi-restart hasta 32 variantes o 250 ms. La RNG es makeRng (Mulberry32-like en packer.ts:51) y el barajado se aplica con shuffleSeeded (packer.ts:61).
4. Greedy placement (placeRuns línea 77): mantiene un slot[] por barra viva con {barId, nextStart}; para cada cut busca el primer slot donde nextStart + cut.lengthMm + kerfMm ≤ spec.lengthMm. Si no entra, abre una barra nueva con kerf = 0 en el primer cut.
5. Best of N — elige la variante con menor waste total; desempata por menor totalBars (líneas 192-201).
6. Output inmutable: LinearResult con bars, cuts, unusedByBar, wasteMmByBar, totalMl, totalBars, cfg.

El spec.bar se construye a partir del primer item: profileId + lengthMm = profile.nominalLengthMm (largo nominal del catálogo). Todos los items del pack deben compartir perfil — si mezclás listones de 50×75 con varillas de 25×25, el packer aplica el perfil del primero a todos (con un warning por consola si hay mismatch).

Workbench (src/ui/lineales-panel/workbench.ts):

• Una banda horizontal por barra, con width = (lengthMm / maxLength) × 100%.
• Los cortes son bloques cobalt (var(--cobalt)) con texto embebido (name · lengthMm).
• El remanente es un gradiente rayado 45° sobre el tramo no ocupado (entre el último corte y bar.lengthMm).
• El label arriba (bar-N · 50×75 · 2400 mm) y el stats abajo (N cortes · total mm usado · M mm retazo).

El remanente está representado visualmente pero no se trackea como remnantOfBarId en el output — solo queda en unusedByBar[barId] como {startMm, lengthMm} para futuro uso (reutilización de retazos entre obras). El spec §3.10 lo marca como pendiente.

10 · Exportar (CSV · XLSX · PDF) + atajos

El botón Exportar ([data-action="export-toggle"]) del header abre un popover con tres opciones. Cada handler vive en src/export/actions-linear.ts y se cablea vía setLinealesHandlers({ onExport }) en src/ui/lineales-panel.ts:33:

El export respeta state.settings.exportVisibleOnly igual que el resto de la app (default true). Si el módulo está apagado, los 4 items del menú Export se ocultan vía src/ui/topbar/sections/state-apply.ts:146-166.

Atajos del flujo

El panel [L] no captura el atajo L simple (reservado para futuro List view del sidebar). El modificador Shift lo desambigua y deja el shortcut simple libre.

Pipeline integrado

El LinearResult se cablea hacia abajo en cuatro destinos:

Multiplicador de obra ×N: si state.settings.projectMultiplier = 3 y tenés 4 listones ×2400, el packer recibe 12 items en lugar de 4 (no clona meshes 3D — las lineales no tienen). El contador de barras se recalcula automáticamente vía recalculateIfResult() (lineales-panel.ts:174), que re-corre el pack si hay linearResult previo en disco.

En Mac el modificador de sistema es ⌘; en otros sistemas Ctrl.