Skip to content

Commit d2e62db

Browse files
author
cranm
committed
desarrollo de documentación /docs y ajusters al README
1 parent 34d07db commit d2e62db

5 files changed

Lines changed: 466 additions & 176 deletions

File tree

‎README.md‎

Lines changed: 153 additions & 176 deletions
Original file line numberDiff line numberDiff line change
@@ -1,155 +1,136 @@
11
# BarroCode
22

3-
Herramienta web para convertir curvas (.svg) en trayectorias oscilantes (.gcode) para el modelado por deposición líquida. Diseñada para quienes trabajan con extrusoras de arcilla y máquinas CNC.
3+
Herramienta web para convertir curvas `.svg` en trayectorias oscilantes `.gcode` para modelado por deposición líquida. Está pensada para extrusoras de arcilla y máquinas CNC donde importa sostener flujo, continuidad de capa y control geométrico.
44

5-
---
5+
BarroCode toma un dibujo vectorial como línea central, lo muestrea sobre su longitud de arco y desplaza cada punto con una figura local de Lissajous. El resultado es una trayectoria imprimible por capas, con unión suave entre alturas, Z-hop sobre cruces, viajes concéntricos y exportación directa a G-code.
66

7-
## Pendientes
8-
```
9-
Slider de coordenadas para ubicar un eje z en el espacio de trabajo para que funcione como centro, y que dentro de los paramametros del keyframe pueda escalar esa curva en particular, como para hacer gradaciones de escala, en relación a las trayectorias. Este slider es vertical, en el mismo estilo que todo lo demás, se ubica en una columna de ancho 1/5 del tercio de panel inferior. Se posiciona a en el centro, entre la visualización de lissajous y el visualizador del gcode.
10-
11-
Make a zhop-like movement a bit before, during, and after the line intersects itself or another line at each layer height, so as not to interrupt the flow of clay when printing.
12-
13-
In the trayectory vis, make the line stroke subtly adjust according to the zoom level on the panel. Also, make their color a bit more saturated and a bit lighter. It looks too dull currently.
14-
15-
(v2) Que un plano normal a cada vector de la dirección actual en la trayectori sea el lugar donde se evalua y desplaza el punto cada lissajous, para generar una trayectoria helicoidal y no plana entre capas; así se suaviza el transito entre capas.
16-
17-
COlores: keyframes individually colored according to ther location along the trayectory, reflecting the visualization marker color at that point.
18-
19-
eje n y eje t tienen dos colores en los acentos, pero esos no tienen relación con la visualización de lissajou, deberías estilizar los paneles de ejes igual que el de acoplamiento de fase. También, en esa letra negra que se usa para todos los valores numéricos; bajarle un poco lo oscuro; si ahora está en un value 10, dame un value 9.
20-
21-
Make "Drop svg box" smaller. Logo 50% biggger
22-
```
23-
24-
## Inicio rápido
7+
## Inicio Rápido
258

269
```bash
2710
npm install
2811
npm run dev
2912
```
3013

31-
Abre la URL que aparece en la terminal (normalmente `http://localhost:5173`).
14+
Abre la URL que aparece en la terminal, normalmente `http://localhost:5173`.
3215

33-
### Build de producción
16+
Para generar una versión estática:
3417

3518
```bash
3619
npm run build
3720
```
3821

39-
Genera la versión web estática en `dist/`. Esa carpeta puede servirse desde cualquier servidor estático o publicarse en GitHub Pages (ver `.github/workflows/deploy.yml`).
40-
41-
---
42-
43-
## Cómo funciona
44-
45-
El trayecto de impresión es la **suma de dos movimientos independientes**:
46-
47-
```
48-
punto_final(s) = línea_central(s) ← trayecto global del SVG
49-
+ N(s) · ampN · sin(2π·s/λN + δ) ← oscilación lateral (normal)
50-
+ T(s) · ampT · sin(2π·s/λT) ← oscilación adelante/atrás (tangente)
22+
El build queda en `dist/` y puede servirse desde cualquier servidor estático o publicarse en GitHub Pages.
23+
24+
## Qué Genera
25+
26+
- **Entrada:** un SVG con `<path>`, `<polyline>`, `<polygon>`, `<line>`, `<circle>`, `<ellipse>` o `<rect>`.
27+
- **Proceso:** muestreo por longitud de arco, marco local tangente/normal, onda de Lissajous, apilado por capas y optimización de viajes.
28+
- **Salida:** G-code absoluto en milímetros, con opción de extrusión `E`.
29+
- **Uso previsto:** impresión continua de arcilla, sin retracción, con trayectorias orgánicas controladas desde una curva central.
30+
31+
```mermaid
32+
flowchart LR
33+
A["SVG importado"] --> B["Muestreo de trayectos"]
34+
B --> C["Marco local T/N"]
35+
C --> D["Onda de Lissajous"]
36+
D --> E["Capas con Z"]
37+
E --> F["Previsualización"]
38+
E --> G["G-code"]
39+
H["Parámetros y keyframes"] --> D
40+
H --> E
5141
```
5242

53-
- `s` = longitud de arco acumulada a lo largo del camino SVG (en mm)
54-
- `N(s)` = vector normal unitario en `s` (perpendicular al trayecto, apunta a la izquierda del sentido de avance)
55-
- `T(s)` = vector tangente unitario en `s` (sentido de avance)
56-
- Las longitudes de onda (`λN`, `λT`) se miden **sobre el arco**, no sobre un eje recto, por lo que el patrón es consistente sin importar la curvatura del camino
57-
- `δ` (delta) es la diferencia de fase entre N y T — controla la **forma de Lissajous** (0° = línea, 90° = elipse cuando λN = λT, etc.)
58-
59-
La previsualización **Marco del extrusor** en el panel inferior izquierdo muestra únicamente la figura de Lissajous en coordenadas locales (T, N), desacoplada completamente de la forma del trayecto global. Úsala para afinar la figura antes de preocuparte por el camino.
60-
61-
---
62-
63-
## Flujo de uso
64-
65-
### 1. Cargar un SVG
66-
67-
Arrastra un archivo SVG al área de carga o haz clic en ella.
68-
69-
El sistema lee elementos `<path>`, `<polyline>`, `<polygon>`, `<line>`, `<circle>`, `<ellipse>` y `<rect>`.
70-
71-
Si no tienes un archivo a mano, haz clic en **"Cargar SVG de ejemplo"** — incluye una curva en S, una elipse y una línea diagonal.
72-
73-
### 2. Revisar la lista de trayectos
74-
75-
Cada elemento geométrico detectado aparece en la lista **Trayectos SVG**:
76-
77-
- Activa o desactiva trayectos individualmente.
78-
- Sobreescribe la **amplitud** o la **longitud de onda** por trayecto (si lo dejas en blanco, se usa el valor global).
43+
## Cómo Funciona
7944

80-
### 3. Ajustar parámetros
45+
El trayecto de impresión es la suma de una línea central y dos oscilaciones locales:
8146

82-
#### Panel izquierdo — parámetros de impresión
83-
84-
| Parámetro | Efecto |
85-
|---|---|
86-
| **Espaciado de muestras** | Densidad de muestreo del camino (unidades SVG). Menor valor = onda más suave, más puntos. |
87-
| **Altura de capa** | Incremento Z entre capas apiladas (mm). |
88-
| **Número de capas / Altura total** | Controla cuántas capas se generan. Puedes definirlo por cantidad de capas o por altura total. |
89-
| **Offset Z de boquilla** | Se suma al Z de cada capa (calibración de primera capa). |
90-
| **Z seguro** | Altura a la que se mueve la boquilla durante los desplazamientos entre trayectos. |
91-
| **Factor de escala** | Convierte unidades SVG a mm. Usá `1` si tu SVG está dibujado en mm; `0.2645` para píxeles a 96 dpi. |
92-
| **Origen X / Y** | Desplaza toda la impresión sobre la cama (mm). |
93-
| **Invertir Y** | Espeja el eje Y (el eje Y de SVG crece hacia abajo; la mayoría de las impresoras lo quieren hacia arriba). |
94-
| **Velocidad de impresión / desplazamiento** | mm/min para movimientos de extrusión y de viaje. |
95-
| **Generar valores E** | Incluye la columna E en el G-code. Desactivalo para una salida de solo movimiento. |
96-
| **Multiplicador de extrusión** | Unidades E por mm de desplazamiento. Ajustalo a tu sistema de bomba o tornillo sin fin (típico: 0.02–0.1). |
97-
| **Transición suave entre capas** | Conecta el final de la capa N con el inicio de la capa N+1 con un movimiento continuo (interpola XY con smoothstep y Z linealmente). Sin retracción ni levantamiento — ideal para arcilla. |
98-
| **Longitud de transición** | Longitud en mm del tramo de unión entre capas. |
99-
| **Dirección alternada** | Las capas impares imprimen en sentido inverso, lo que reduce la deriva direccional en arcilla. |
100-
| **Cerrar trayecto** | Agrega un movimiento de regreso al inicio de cada trayecto (útil para elipses y formas cerradas). |
101-
| **Pausa al inicio** | Pausa G4 (ms) en la primera posición de impresión, dándole tiempo a la arcilla para comenzar a fluir. |
102-
| **Movimiento de cebado** | Extrude una línea corta antes de la impresión principal para cebar la boquilla. |
103-
104-
#### Panel derecho — parámetros de Lissajous
105-
106-
| Parámetro | Efecto |
107-
|---|---|
108-
| **Amplitud N** | Semi-amplitud de la oscilación lateral (mm). El trayecto se desvía esta distancia hacia los lados del centro. |
109-
| **Amplitud T** | Semi-amplitud de la oscilación adelante/atrás (mm). |
110-
| **Longitud de onda N / T** | Longitud de arco de un ciclo completo de onda (mm). Se mide sobre la curva. |
111-
| **Delta (δ)** | Diferencia de fase entre N y T. Controla la forma: 0° = línea, 90° = elipse (si λN = λT), valores intermedios = formas de Lissajous. |
112-
| **Offset de fase** | Fase inicial de la onda (radianes). |
113-
| **Desfase de fase por capa** | Fase extra que se suma por cada capa — crea una apariencia helicoidal o en espiral. |
114-
115-
Los **preajustes** en la parte superior del panel derecho aplican configuraciones predefinidas de Lissajous con una miniatura visual de la figura resultante.
116-
117-
### 4. Sistema de keyframes
118-
119-
La barra de línea de tiempo debajo de la previsualización 3D permite **anclar valores de Lissajous en puntos específicos del trayecto**:
120-
121-
1. Mové el slider de la línea de tiempo al punto deseado (0% = inicio, 100% = fin).
122-
2. Ajustá los parámetros de Lissajous al valor que querés en ese punto.
123-
3. Hacé clic en **⊕ KF** para crear un keyframe.
124-
4. Entre keyframes, los valores se interpolan linealmente.
125-
126-
Hacé clic en un keyframe (diamante naranja) para seleccionarlo y editar sus valores. El botón **✕** elimina el keyframe seleccionado; el ícono de papelera elimina todos.
127-
128-
### 5. Previsualización 3D
47+
```text
48+
punto_final(s) = línea_central(s)
49+
+ N(s) · ampN · sin(2π·s/λN + δ)
50+
+ T(s) · ampT · sin(2π·s/λT)
51+
```
12952

130-
- **Líneas coloreadas** = trayecto generado, una tonalidad por capa (azul pizarra en la base → terracota en la cima).
131-
- **Líneas punteadas** = transiciones entre capas.
132-
- **Punto animado** = posición del extrusor virtual según la línea de tiempo.
133-
- **Cubo de orientación** (esquina inferior derecha) = muestra los ejes X/Y/Z en tiempo real.
53+
- `s` es la longitud de arco acumulada sobre el camino SVG.
54+
- `N(s)` es el vector normal unitario del trayecto.
55+
- `T(s)` es el vector tangente unitario del trayecto.
56+
- `λN` y `λT` son longitudes de onda medidas sobre el arco, no sobre un eje recto.
57+
- `δ` controla la diferencia de fase entre normal y tangente, y por lo tanto la figura de Lissajous.
58+
59+
```mermaid
60+
flowchart LR
61+
S["s: longitud de arco"] --> C["punto central"]
62+
C --> T["T(s): tangente"]
63+
C --> N["N(s): normal"]
64+
T --> OT["offsetT = ampT * sin(faseT)"]
65+
N --> ON["offsetN = ampN * sin(faseN + delta)"]
66+
OT --> PF["punto final"]
67+
ON --> PF
68+
```
13469

135-
| Control | Acción |
136-
|---|---|
137-
| Arrastrar (botón izquierdo) | Desplazar (pan) |
138-
| Arrastrar (botón derecho) | Rotar (azimut / elevación) |
139-
| Rueda del mouse | Zoom |
140-
| Botón **Ajustar** | Encuadre automático |
70+
La previsualización **Marco del extrusor** muestra la figura de Lissajous en coordenadas locales `(T, N)`, desacoplada del trayecto global. Sirve para afinar la forma de la oscilación antes de evaluar cómo se adapta al SVG.
71+
72+
## Flujo De Uso
73+
74+
```mermaid
75+
sequenceDiagram
76+
participant U as Usuario
77+
participant UI as BarroCode UI
78+
participant SVG as Parser SVG
79+
participant W as Generador de ondas
80+
participant G as Generador G-code
81+
82+
U->>UI: Carga un SVG
83+
UI->>SVG: parseSVG(raw, spacing)
84+
SVG-->>UI: Trayectos muestreados
85+
U->>UI: Ajusta parámetros y keyframes
86+
UI->>W: generateWaveLayers(paths, params, keyframes)
87+
W-->>UI: Capas y trayectoria
88+
UI->>G: generateGcode(layers, params)
89+
G-->>UI: Texto .gcode
90+
U->>UI: Descarga archivo
91+
```
14192

142-
### 6. Exportar G-code
93+
1. Carga un SVG o usa el archivo de ejemplo.
94+
2. Activa, desactiva o ajusta trayectos individuales.
95+
3. Define muestreo, escala, capas, velocidades y comportamiento de arcilla.
96+
4. Ajusta amplitud, longitud de onda y fase de Lissajous.
97+
5. Usa keyframes para interpolar parámetros a lo largo de la trayectoria.
98+
6. Previsualiza capas, transiciones, Z-hop y posición del extrusor.
99+
7. Exporta el `.gcode`.
100+
101+
Los parámetros detallados están en [docs/usage.md](docs/usage.md).
102+
103+
## Arquitectura
104+
105+
```mermaid
106+
flowchart TB
107+
UI["UI React<br/>paneles, timeline, canvas"] --> State["Estado principal<br/>App.tsx"]
108+
State --> Geometry["Geometría SVG<br/>svgParser.ts"]
109+
State --> Toolpath["Trayectoria ondulada<br/>waveGenerator.ts"]
110+
State --> Export["Exportación<br/>gcodeGenerator.ts"]
111+
112+
Geometry --> Sampled["SampledPath<br/>puntos, tangente, normal"]
113+
Sampled --> Toolpath
114+
Params["PrintParams + keyframes"] --> Toolpath
115+
Params --> Export
116+
Toolpath --> Layers["WaveLayer[]"]
117+
Layers --> Preview["Preview2D / LissajousPreview"]
118+
Layers --> Export
119+
Export --> Travel["hopUtils.ts + skirtUtils.ts"]
120+
Export --> File["archivo .gcode"]
121+
```
143122

144-
Hacé clic en **↓ Descargar .gcode** para guardar el archivo.
145-
El nombre del archivo coincide con el SVG cargado (ej. `mi-vasija.gcode`).
123+
- `src/lib/svgParser.ts` inserta el SVG en un contenedor oculto y usa la API SVG del navegador para medir longitudes y puntos.
124+
- `src/lib/waveGenerator.ts` calcula offsets de Lissajous, keyframes, escala alrededor de centro y capas.
125+
- `src/lib/gcodeGenerator.ts` convierte capas a G-code, ordena trayectos por nearest-neighbor, aplica soft join, Z-hop y viajes concéntricos.
126+
- `src/components/Preview2D.tsx` dibuja la previsualización ortográfica en Canvas.
146127

147-
---
128+
Más detalle técnico en [docs/architecture.md](docs/architecture.md).
148129

149-
## Estructura del G-code generado
130+
## G-code Generado
150131

151132
```gcode
152-
; Encabezado con todos los valores de parámetros
133+
; Encabezado con valores de parámetros
153134
G21 ; unidades en mm
154135
G90 ; posicionamiento absoluto
155136
G92 E0 ; resetear extrusión
@@ -162,69 +143,65 @@ G1 X.. Y.. E.. F600 ; impresión
162143
...
163144
```
164145

165-
---
166-
167-
## Geometría de la onda
168-
146+
La estrategia de desplazamientos ordena trayectos por cercanía y evita saltos largos cuando corresponde:
147+
148+
```mermaid
149+
flowchart TD
150+
A["Trayectos de una capa"] --> B["Calcular punto inicial y final"]
151+
B --> C["Elegir trayecto más cercano"]
152+
C --> D["Emitir impresión"]
153+
D --> E{"¿Quedan trayectos?"}
154+
E -- "sí" --> C
155+
E -- "no" --> F{"¿softJoin activo?"}
156+
F -- "sí" --> G["Transición continua a la siguiente capa"]
157+
F -- "no" --> H["Viaje con arco concéntrico o salto corto"]
169158
```
170-
fase = 2π × arcoLongitud / longitudDeOnda + offsetFase + índiceCapa × desfasePorCapa
171-
offsetN = amplitudN × sin(fase + delta)
172-
offsetT = amplitudT × sin(fase)
173-
punto = puntoCentral + normal × offsetN + tangente × offsetT
174-
```
175-
176-
- `normal` es el vector perpendicular al trayecto en cada muestra.
177-
- `arcoLongitud` es la distancia acumulada a lo largo de la curva — la longitud de onda siempre se mide sobre el camino, independientemente de su forma.
178-
- Para curvas cerradas (círculos, elipses), la onda cierra sin discontinuidades.
179-
180-
---
181159

182-
## Optimización de desplazamientos
160+
## Limitaciones Conocidas
183161

184-
Al cambiar de capa, la herramienta aplica una estrategia **nearest-neighbor** para ordenar los trayectos de forma que minimice la distancia total de los saltos entre ellos. Esto reduce el tiempo de impresión y la cantidad de movimientos que cruzan el área ya impresa.
162+
- **Transforms anidados complejos en SVG:** los transforms simples sobre elementos individuales funcionan bien; grupos profundamente anidados pueden no resolverse completamente.
163+
- **Unidades SVG no son mm por defecto:** ajusta el factor de escala según el sistema de coordenadas del archivo.
164+
- **Sin retracción:** la salida está orientada a arcilla, donde cortar flujo suele ser indeseable.
165+
- **Modelo de extrusión lineal:** `E += distancia * multiplicador`.
166+
- **Sin malla de nivelación de cama.**
185167

186-
---
168+
## Estructura Del Proyecto
187169

188-
## Limitaciones conocidas
189-
190-
- **Transforms anidadas complejas en SVG**: los transforms simples (traslación, rotación) sobre elementos individuales funcionan bien. Transforms sobre grupos `<g>` profundamente anidados pueden no resolverse completamente.
191-
- **Unidades SVG ≠ mm por defecto**: ajustá el factor de escala según el sistema de coordenadas de tu SVG.
192-
- **Sin retracción**: el G-code generado no incluye movimientos de retracción (la impresión en arcilla raramente los requiere).
193-
- **Modelo de extrusión lineal**: `E += distancia × multiplicador`. Adecuado para extrusoras de arcilla por presión de aire o tornillo sin fin.
194-
- **Sin malla de nivelación de cama**.
195-
196-
---
197-
198-
## Estructura del proyecto
199-
200-
```
170+
```text
201171
src/
202-
types/index.ts tipos TypeScript compartidos
172+
types/index.ts
203173
lib/
204-
svgParser.ts parseo de SVG y muestreo de trayectos (usa el DOM SVG del navegador)
205-
waveGenerator.ts matemática de la onda de Lissajous, apilado de capas y keyframes
206-
gcodeGenerator.ts formato de G-code, optimización nearest-neighbor y descarga
174+
svgParser.ts
175+
waveGenerator.ts
176+
gcodeGenerator.ts
177+
hopUtils.ts
178+
skirtUtils.ts
207179
components/
208-
App.tsx estado principal y flujo de datos
209-
PathParams.tsx UI de parámetros de impresión (panel izquierdo)
210-
LissajousParams.tsx UI de parámetros de Lissajous y preajustes (panel derecho)
211-
PathList.tsx lista de trayectos con activación y sobreescritura por trayecto
212-
Preview2D.tsx previsualización 3D ortográfica con línea de tiempo y keyframes
213-
LissajousPreview.tsx previsualización animada de la figura de Lissajous
214-
GcodeOutput.tsx visualización y descarga del G-code
215-
NumInput.tsx input numérico con soporte de scroll para cambiar valores
180+
PathParams.tsx
181+
LissajousParams.tsx
182+
PathList.tsx
183+
Preview2D.tsx
184+
LissajousPreview.tsx
185+
GcodeOutput.tsx
186+
CenterScaleParams.tsx
187+
NumInput.tsx
216188
public/
217-
sample.svg archivo de prueba incluido
218-
logo.png logotipo completo
219-
isotype.png isotipo (ícono cuadrado)
220-
fonts/ GSCode variable font
221-
dist/ salida del build estático (GitHub Pages)
189+
sample.svg
190+
logo.png
191+
isotype.png
192+
fonts/
193+
dist/
222194
```
223195

224-
---
196+
## Documentación
197+
198+
- [docs/usage.md](docs/usage.md): flujo de uso y parámetros.
199+
- [docs/architecture.md](docs/architecture.md): pipeline interno y responsabilidades.
200+
- [docs/fabrication-notes.md](docs/fabrication-notes.md): criterios de fabricación con arcilla.
201+
- [pendientes.md](pendientes.md): notas de trabajo abiertas.
225202

226203
## Tecnologías
227204

228-
- [Vite 5](https://vitejs.dev/) + [React 18](https://react.dev/) + TypeScript (strict)
229-
- Canvas API para previsualización (sin WebGL)
230-
- Sin dependencias de UI externas — todo el sistema de diseño está en `src/index.css`
205+
- [Vite 5](https://vitejs.dev/) + [React 18](https://react.dev/) + TypeScript strict.
206+
- Canvas API para previsualización.
207+
- Sin dependencias de UI externas; el sistema visual vive en `src/index.css`.

0 commit comments

Comments
 (0)