9. cartesiano Manual de uso del script: Graficador cartesiano interactivo para Moodle

# Manual de uso del script: Graficador cartesiano interactivo para Moodle

## 1. ¿Qué es este script?

Es un graficador en SVG pensado para Moodle. Permite dibujar funciones matemáticas dentro de elementos `<svg>`, con zoom, arrastre, leyenda, puntos y algunos cálculos auxiliares.

La versión actual ya incorpora dos mejoras importantes:
- un **evaluador matemático nuevo**, con parser real;
- la **fusión de las reparaciones de zoom** para tangente y funciones racionales.

## 2. Qué puede hacer

- Graficar una o varias funciones en el mismo plano.
- Dibujar ejes y grilla.
- Usar rangos personalizados en X e Y.
- Definir pasos numéricos normales, en múltiplos de `pi` o de `e`.
- Mostrar leyenda.
- Soportar zoom con rueda o pellizco y arrastre del plano.
- Mantener escala 1:1 opcional.
- Dibujar puntos explícitos.
- Dibujar puntos calculados a partir de un valor de `x`.
- Dibujar intersecciones con una horizontal `y = c`.
- Recortar correctamente funciones que salen del área visible.
- Manejar mejor funciones problemáticas como `tan(x)`, racionales tipo `1/(x-1)`, `log(x)` y `sqrt(x)`.

## 3. Cómo se activa

El script se inicializa automáticamente sobre todos los SVG cuyo id comience con `grid-`.

Ejemplo mínimo:

```html
<svg id="grid-1"
     width="640"
     height="420"
     data-range-x="-10,10"
     data-range-y="-10,10"
     data-funcs="x^2"
     data-labels="y=x^2"
     data-colors="#d32f2f"
     data-legend="true"></svg>
```

## 4. Atributos principales del SVG

### Obligatorio en la práctica

- `id="grid-..."`  
  El script solo procesa SVG cuyo id comience con `grid-`.

### Rango y aspecto

- `data-range-x="xmin,xmax"`
- `data-range-y="ymin,ymax"`
- `data-lock-aspect="true|false"`  
  Si está en `true`, intenta mantener escala 1:1.

### Funciones

- `data-funcs="expr1;expr2;expr3"`
- `data-labels="etiqueta1;etiqueta2;etiqueta3"`
- `data-colors="#color1;#color2;#color3"`

### Grilla y marcas

- `data-step-x="valor"`
- `data-step-y="valor"`

Acepta valores como:
- `1`
- `0.5`
- `pi`
- `pi/2`
- `2*pi`
- `e`
- `e/2`

### Interacción

- `data-mode="interactive"` permite zoom y arrastre.
- `data-mode="snapshot"` deja el gráfico fijo.

### Recorte visual

- `data-clip="true|false"`

En general conviene dejarlo en `true`.

### Leyenda

- `data-legend="true"`

### Puntos

- `data-points="(x1,y1);(x2,y2)"`
- `data-point-x="x0;expr;x1;expr2"`
- `data-point-y="y0;expr;y1;expr2"`

## 5. Expresiones admitidas

### Variable

- `x`

### Constantes

- `pi`
- `e`

También reconoce y normaliza:
- `π` como `pi`

### Operadores

- `+`
- `-`
- `*`
- `/`
- `^`

### Multiplicación implícita

El evaluador nuevo soporta multiplicación implícita en muchos casos típicos. Por ejemplo:

- `2(x+1)`
- `3pi`
- `x(x-1)`
- `(x+1)(x-1)`
- `2sin(x)`

### Funciones admitidas

- `sin(x)`
- `cos(x)`
- `tan(x)`
- `asin(x)`
- `acos(x)`
- `atan(x)`
- `log(x)`
- `ln(x)`
- `log10(x)`
- `log2(x)`
- `logb(valor,base)`
- `pow(a,b)`
- `sqrt(x)`
- `abs(x)`
- `exp(x)`
- `floor(x)`
- `ceil(x)`
- `round(x)`
- `sign(x)`
- `min(a,b,...)`
- `max(a,b,...)`

### Alias que también entiende

Durante la normalización, el evaluador convierte automáticamente:

- `sen(x)` → `sin(x)`
- `tg(x)` → `tan(x)`
- `×` o `·` → `*`
- `÷` → `/`
- guiones tipográficos raros → `-`

### Cosas importantes del evaluador nuevo

- Ya **no depende de una regex simple** para interpretar `^`.
- Ya **no usa `new Function(...)` como motor principal de evaluación**.
- Ahora procesa la expresión con:
  - normalización,
  - tokenización,
  - inserción de multiplicación implícita,
  - parser recursivo,
  - AST,
  - evaluador interno compilado y cacheado.

### Ejemplos que ahora interpreta correctamente

- `x^2+1`
- `2*x^2-3`
- `(x+1)^2`
- `2^3^2`
- `-x^2`
- `(-x)^2`
- `2(x+1)`
- `sen(pi/2)`
- `tg(pi/4)`
- `1E-3*x`
- `logb(8,2)`
- `min(2,x,5)`

### Qué pasa con expresiones inválidas

Si la expresión tiene:
- símbolos no permitidos,
- nombres no permitidos,
- funciones mal escritas,
- cantidad incorrecta de argumentos,
- sintaxis rota,

el evaluador devuelve `NaN` y la curva no se dibuja correctamente en esa parte.

## 6. Ejemplos de uso

### Ejemplo 1: una sola función

```html
<svg id="grid-parabola"
     width="640"
     height="420"
     data-range-x="-5,5"
     data-range-y="-2,12"
     data-funcs="x^2"
     data-labels="y=x^2"
     data-colors="#d32f2f"
     data-legend="true"></svg>
```

### Ejemplo 2: varias funciones

```html
<svg id="grid-varias"
     width="640"
     height="420"
     data-range-x="-2*pi,2*pi"
     data-range-y="-2,2"
     data-step-x="pi/2"
     data-step-y="0.5"
     data-funcs="sin(x);cos(x);tan(x)"
     data-labels="sen(x);cos(x);tan(x)"
     data-colors="#d32f2f;#1976d2;#388e3c"
     data-legend="true"
     data-lock-aspect="false"></svg>
```

### Ejemplo 3: puntos explícitos

```html
<svg id="grid-puntos"
     width="640"
     height="420"
     data-range-x="-5,5"
     data-range-y="-5,5"
     data-funcs="x"
     data-points="(0,0);(1,1);(2,2);(-2,-2)"
     data-legend="true"></svg>
```

### Ejemplo 4: punto calculado para un valor de x

```html
<svg id="grid-px"
     width="640"
     height="420"
     data-range-x="-5,5"
     data-range-y="-5,10"
     data-funcs="x^2-1"
     data-point-x="2;x^2-1;-1;x^2-1"
     data-legend="true"></svg>
```

Eso dibuja, además de la curva, los puntos correspondientes a `x=2` y `x=-1`.

### Ejemplo 5: intersecciones con una horizontal

```html
<svg id="grid-py"
     width="640"
     height="420"
     data-range-x="-5,5"
     data-range-y="-5,5"
     data-funcs="x^2-4"
     data-point-y="0;x^2-4"
     data-legend="true"></svg>
```

Eso busca los puntos donde la función corta a la recta `y=0`.

### Ejemplo 6: racional con asíntota

```html
<svg id="grid-racional"
     width="640"
     height="420"
     data-range-x="-6,6"
     data-range-y="-10,10"
     data-funcs="1/(x-1)"
     data-labels="y=1/(x-1)"
     data-colors="#7b1fa2"
     data-legend="true"></svg>
```

### Ejemplo 7: multiplicación implícita

```html
<svg id="grid-implicita"
     width="640"
     height="420"
     data-range-x="-5,5"
     data-range-y="-5,20"
     data-funcs="2(x+1);x(x-2)"
     data-labels="2(x+1);x(x-2)"
     data-colors="#ef6c00;#00897b"
     data-legend="true"></svg>
```

### Ejemplo 8: modo fijo para material impreso o captura

```html
<svg id="grid-fijo"
     width="640"
     height="420"
     data-range-x="-10,10"
     data-range-y="-10,10"
     data-funcs="abs(x)"
     data-mode="snapshot"></svg>
```

## 7. Qué problemas hubo en el desarrollo y cómo se solucionaron

### Problema 1: el operador `^` se interpretaba mal

Antes se intentó convertir `^` usando una regex simple. Eso podía romper expresiones como:

- `x^2+1`
- `2*x^2-3`
- `(x+1)^2`
- `2^3^2`
- `-x^2`

#### Solución

Se reemplazó la lógica antigua por un evaluador real con:
- normalización,
- tokenización,
- multiplicación implícita,
- parser recursivo,
- construcción de AST,
- evaluador interno cacheado.

Con eso la potencia ya respeta mejor precedencia, signos y estructura de paréntesis.

---

### Problema 2: el rendimiento del evaluador era innecesariamente caro

Antes el sistema podía recompilar la expresión demasiadas veces al dibujar muchos puntos.

#### Solución

Ahora las expresiones compiladas se guardan en caché. La idea es:
- la expresión se interpreta una vez;
- se arma su evaluador interno;
- luego ese evaluador se reutiliza en los siguientes puntos.

---

### Problema 3: la tangente unía ramas distintas al hacer zoom out

Con `tan(x)` se producían líneas falsas cerca de las asíntotas verticales. En rangos moderados del eje Y funcionaba bien, pero al ampliar más el zoom out el muestreo quedaba demasiado grueso y la curva saltaba de un lado al otro.

#### Solución

Se hicieron varias mejoras:
- detección especial para expresiones con `tan(`,
- uso de umbrales basados en pantalla y no solo en rango matemático,
- análisis del salto mediante `atanYes` para detectar mejor los cambios de rama,
- reducción adaptativa del tamaño de paso cuando la expresión contiene tangente.

---

### Problema 4: las racionales tipo `1/(x-1)` presentaban un efecto parecido

Aunque no son periódicas como `tan(x)`, también tienen asíntotas verticales. Al alejar mucho la vista podían aparecer uniones incorrectas.

#### Solución

Se agregó tratamiento especial para expresiones clasificadas como racionales:
- paso adaptativo más fino,
- revisión del punto medio del intervalo,
- ruptura forzada si el valor intermedio explota,
- uso de `atanYes` y detección de magnitudes fuera de pantalla.

---

### Problema 5: apareció una regresión al cambiar el evaluador

Cuando se integró el evaluador nuevo, al principio reaparecieron problemas de zoom que ya estaban reparados. No era culpa del parser nuevo en sí, sino que al reemplazar bloques del script se había retrocedido en parte de la lógica de dibujo y muestreo.

#### Solución

Se hizo una **versión fusionada** que combina:
- evaluador nuevo,
- reparaciones de zoom para `tan(x)`,
- reparaciones de zoom para racionales.

Esa versión fusionada es la base correcta para seguir trabajando.

---

### Problema 6: el clipping era demasiado optimista

Había intervalos donde el script asumía continuidad y trataba de unir extremos, cuando entre ambos en realidad había una discontinuidad o una explosión de valores.

#### Solución

Se mejoró el refinamiento con:
- `intervalLooksContinuous(...)`,
- revisión recursiva por mitades,
- profundidad máxima controlada,
- límite de chequeos,
- límite de tiempo para no afectar demasiado el rendimiento.

## 8. Cosas importantes que hay que recordar si más adelante quieres seguir reparándolo

### 1. La detección de discontinuidades sigue siendo heurística

No es un sistema de análisis simbólico completo. Usa pistas como:
- presencia de `tan(`,
- presencia de `/` para racionales,
- saltos grandes,
- valores enormes,
- diferencias angulares con `atanYes`.

Funciona bastante bien, pero no garantiza perfección absoluta en todas las funciones posibles.

### 2. Los casos más delicados siguen siendo las asíntotas verticales

Los casos más sensibles son:
- `tan(x)`
- `1/x`
- `1/(x-a)`
- `cos(x)/sin(x)`
- `1/cos(x)`
- expresiones que explotan en un punto

Si reaparecen líneas raras, normalmente hay que mirar estas partes:
- `classifyExpr(...)`
- `shouldForceBreak(...)`
- `intervalLooksContinuous(...)`
- el cálculo de `step`

### 3. El problema casi siempre aparece al hacer zoom out

Cuando el rango visible crece mucho:
- el paso tiende a ser más grande,
- una sola muestra puede saltar una rama completa,
- el clipping puede creer que hubo continuidad.

Por eso cualquier reparación futura debe pensarse especialmente para zoom out extremo.

### 4. El evaluador nuevo ya no es el punto débil principal

Antes el gran problema era la interpretación de expresiones. Con el parser nuevo eso mejoró mucho.

Ahora, si reaparece un problema serio, lo más probable es que esté en:
- muestreo,
- clipping,
- zoom,
- detección de discontinuidades,

más que en la lectura básica de la fórmula.

### 5. `data-point-y` es aproximado

La búsqueda de intersecciones con `y=c` usa barrido numérico e interpolación lineal. Por eso:
- puede no detectar todas las intersecciones si están muy juntas,
- puede ser aproximado en curvas complicadas,
- depende del rango visible y del paso de muestreo.

### 6. `classifyExpr(...)` no entiende toda la matemática

Solo clasifica de forma simple. No sabe, por ejemplo, que una expresión complicada puede esconder una discontinuidad si no aparece con los patrones esperados.

### 7. El script está pensado para SVG, no para canvas

Todo el dibujo se hace en polylines SVG. Eso facilita integrarlo en Moodle y mantiene buena nitidez, pero también implica que el rendimiento depende de cuántos segmentos se generen.

### 8. El bloqueo de escala 1:1 puede cambiar tu rango visible

Si `data-lock-aspect="true"`, el gráfico puede ajustar automáticamente el rango X o Y para conservar la proporción. Esto no es un error: es parte del diseño.

## 9. Recomendaciones prácticas de uso

- Para funciones con asíntotas, evita partir con rangos exageradamente grandes.
- Deja `data-clip="true"` salvo que tengas una razón clara para desactivarlo.
- Usa `data-lock-aspect="false"` cuando quieras controlar manualmente el rango vertical sin que el script lo modifique.
- Si vas a mostrar `tan(x)`, conviene usar pasos en X razonables, por ejemplo `pi/2` o `pi/4` para la grilla.
- Si quieres materiales estáticos, usa `snapshot`.
- Si quieres exploración en clase, usa `interactive`.
- Si una expresión no dibuja bien, prueba primero si hay un error de sintaxis o una función no permitida.

## 10. Resumen rápido

Este script ya resuelve bastante bien:
- funciones polinómicas,
- trigonométricas básicas,
- racionales sencillas,
- logaritmos,
- raíces,
- puntos e intersecciones,
- zoom y arrastre.

Los puntos delicados siguen siendo los típicos de un graficador por muestreo:
- asíntotas verticales,
- zoom out extremo,
- funciones con cambios muy bruscos.

La base actual correcta es la **versión fusionada**, porque junta:
- evaluador nuevo,
- caché,
- parser real,
- reparaciones de zoom para tangente y racionales.

Si en el futuro reaparece un problema visual, casi seguro habrá que revisar primero la lógica de muestreo y la detección de cortes de tramo.