kapycode: tu modelo como texto

Octava y última entrega de la serie «Por dentro de KapyCAD 2»; lo que describe llegará con KapyCAD 2, que aún no hemos publicado. Un modelo paramétrico es, en el fondo, una receta: dibuja este croquis, extrúyelo diez milímetros, redondea estas aristas. En KapyCAD esa receta ya está ahí, en el historial de operaciones. Lo que le falta es una forma que puedas leer de corrido, copiar, comparar o escribir tú.

En KapyCAD 2, cada documento tendrá una forma de texto, y la llamamos kapycode. Es el mismo documento, escrito de otra manera.

Un modelo que se puede leer

Empecemos por un ejemplo. Esta es una caja de 50 × 30 milímetros, extruida 10 y con las cuatro aristas verticales redondeadas. Así lo escribe la versión en desarrollo (los nombres por defecto se guardan en inglés); hemos quitado algunos campos (donde ves …) para que quepa:

@name("Sketch 1")
sketch sketch_1 on FacePlane(…):
    origin = (=0, =0)
    p_4f288929 = (50, 30)
    p_71df89f1 = (0, 30)
    p_92663e95 = (50, 0)
    L_09bfea4f = line(origin, p_92663e95)
    L_499b27c9 = line(p_4f288929, p_71df89f1)
    L_8271bf8e = line(p_92663e95, p_4f288929)
    L_a7ba82a2 = line(p_71df89f1, origin)
    horizontal L_09bfea4f
    horizontal L_499b27c9
    vertical L_8271bf8e
    vertical L_a7ba82a2
    dist origin p_92663e95 = 50
    dist origin p_71df89f1 = 30

@name("Extrude 1")
extrude_1 = extrude(combineMode="new", endCondition="blind", height1=10, sketchId=sketch_1, …)

@name("Fillet 1")
fillet_1 = fillet(edgeQuery=edges() where vertical, radius=2, targetBodyId=body_1, …)

Se lee casi solo. Un croquis con cuatro puntos y cuatro líneas (los nombres raros son los identificadores internos de cada elemento). Una esquina es el origen, que el =0 deja fijo; dos lados son horizontales y dos verticales, y dos cotas fijan el ancho en 50 y el alto en 30, así que el rectángulo queda totalmente definido. Después, una extrusión de 10 que usa ese croquis y un redondeo de radio 2 sobre las aristas verticales del cuerpo. Las líneas @name son los nombres que ves en el historial.

Hay una sola forma de escribir cada cosa. El texto lo produce un formateador canónico, como los que traen muchos lenguajes de programación: sangría de cuatro espacios, una sentencia por línea, sin opciones de estilo. Dos documentos idénticos dan el mismo texto, byte a byte. De eso dependen la ida y vuelta y el diff que vienen a continuación.

Ida y vuelta sin pérdidas

Generar el texto a partir del modelo es la parte fácil. Lo importante es poder volver: editas el texto, vuelves al editor, y el documento es el que dice el texto. Y si no tocas nada, el documento que vuelve es idéntico al que salió.

diagram

«Idéntico» es una palabra fuerte, así que lo medimos en cada cambio con dos tipos de pruebas. La primera usa un documento sintético construido para pasar por todo lo que el formato sabe decir: los treinta tipos de operación, cada variante de cada campo, cada valor posible de cada lista cerrada, cada campo opcional presente y ausente. La segunda pasa por más de cincuenta documentos reales, el conjunto que usamos para esta comprobación: los modelos de los tutoriales, generadores paramétricos y piezas de pruebas de geometría. Cada uno se convierte en texto, se vuelve a leer y se compara con el original campo a campo.

En las dos se cuentan cuatro cosas: valores que cambian en el viaje, listas que vuelven en otro orden, trozos que el texto no sabe expresar y tiene que guardar como un bloque opaco, y partes del formato que ningún documento llega a usar. Las cuatro están a cero, y la regla es que no pueden subir. Además, los documentos de referencia de geometría se abren desde su texto y se regeneran: volúmenes, áreas, cajas, caras y aristas tienen que salir iguales que abriéndolos de la forma normal.

Lo único que el texto deja fuera es lo que se puede recalcular: el estado de un croquis o sus grados de libertad, por ejemplo. Salen de ejecutar la receta, así que no hace falta escribirlos.

Si el texto que escribes tiene un error, no se aplicará nada. La pieza se quedará en su último estado bueno, y el error se marcará en su línea.

Para qué sirve

Tener tu modelo como texto sirve para varias cosas. Algunas llegarán con KapyCAD 2; otras vendrán después.

La primera son los Smart Objects escritos en código. Cuando presentamos los Smart Objects contamos que algunos están definidos por código. En KapyCAD 2 ese código será kapycode, el mismo lenguaje. Por ejemplo, una clavija con dos parámetros:

smartobject peg:
    param d: Length = 10
    param tall: Length = 16
    sketch s on XY:
        c = (0, 0)
        circle(c, d / 2)
    return extrude(s, tall)

Lo ejecutará un intérprete dentro del núcleo de KapyCAD, y será determinista: sin reloj ni azar, el mismo código con los mismos parámetros construirá lo mismo en cualquier máquina. Y tendrá un presupuesto de trabajo: un bucle que no termine se cortará con un error claro en vez de colgar la pestaña.

También se podrán revisar los cambios como un diff. Como el texto es canónico y los nombres no se renumeran solos (volvemos a eso más abajo), un cambio pequeño en el modelo es un cambio pequeño en el texto. Si subes la extrusión de 10 a 24:

-extrude_1 = extrude(combineMode="new", endCondition="blind", height1=10, sketchId=sketch_1, …)
+extrude_1 = extrude(combineMode="new", endCondition="blind", height1=24, sketchId=sketch_1, …)

El diff ocupa una línea. El archivo que descargues de KapyCAD 2 será ese mismo texto, con la versión del formato en su primera línea, así que cualquier herramienta que compare textos te servirá para ver qué cambió entre dos copias de tu modelo.

Y se podrá partir de algo que ya existe. Un fragmento de texto se copia y se pega, así que una pieza que siempre empiezas igual se convierte en un fragmento que pegas al empezar.

El panel de código

En KapyCAD 2, el modo Diseño tendrá un panel de código junto al visor, con tu modelo en kapycode. El texto y el editor estarán sincronizados en los dos sentidos: si cambias height1=10 por height1=24, la pieza crece; si mueves algo en el editor, el texto se actualiza. Lo que escribas solo se aplica cuando se lee y se resuelve sin errores, así que una línea a medio escribir no deja la pieza a medias. Y hay una sola pila de deshacer para las dos cosas: Ctrl+Z deshace en orden lo que hayas cambiado, en el texto o en el editor.

Las preguntas del panel las contesta el ayudante de lenguaje de la cuarta entrega, así que escribir no espera a que termine una regeneración.

Nombres que no se rompen

En el texto se ve enseguida cómo se refiere una línea a otra. sketchId=sketch_1 dice qué croquis usa la extrusión. ¿Qué pasa si borras una operación anterior?

En una versión ingenua, los nombres se derivarían del orden: extrude_1, extrude_2… Borras el primero, el segundo pasa a llamarse extrude_1, y todas las líneas que lo citan cambian aunque no las hayas tocado. En KapyCAD 2 el nombre de cada operación se guardará: nacerá al crearla y solo cambiará si tú la renombras. Y si la renombras desde el panel, todas sus referencias cambiarán con ella.

Un nombre que no existe tampoco pasará en silencio. Si escribes sketchId=sketch_7 y no hay sketch_7, se marcará un error en esa línea y el documento se quedará como estaba.

Las caras y las aristas son el caso difícil, y aquí el texto hereda todo el trabajo que contamos en referencias topológicas estables. En lugar de decir «la arista número 4», una referencia a una arista describe cómo nació: qué operación la creó y desde qué. En el texto aparece así, por ejemplo con bornIn=extrude_1 y el papel que tenía.

Para muchos casos hay algo todavía mejor: una regla. El edgeQuery=edges() where vertical del ejemplo describe cómo encontrar las aristas, sin enumerarlas. Si cambias el rectángulo por un perfil con una muesca, la regla vuelve a buscar y encuentra las aristas verticales que haya ahora. Las reglas admiten filtros como vertical, horizontal o circular, medidas como length > 10 y combinaciones de conjuntos.

Y cuando una edición de texto sí rompería referencias (por ejemplo, reescribir el rectángulo de un croquis como un círculo cuando hay un redondeo colgando de sus aristas), KapyCAD 2 no la aplicará a ciegas: te avisará de cuántos elementos y cuántas referencias se pierden, y te dejará elegir entre «Aplicar igualmente» o «Volver atrás».

Lo que viene

Esta parte describe hacia dónde vamos, sin compromisos ni fechas. Un modelo que es texto, con un lenguaje que se lee y se ejecuta de forma determinista, es una base muy buena para dos cosas.

La primera es automatizar: generar variantes de una pieza o aplicar el mismo cambio a muchas. Para eso mantenemos una regla: todo lo que se pueda escribir tiene que corresponderse con algo que ya puedes hacer desde la interfaz, así que el texto nunca podrá hacer nada que la interfaz no permita.

La segunda es una IA que escriba kapycode. Un formato de texto compacto, con errores precisos en su línea y una ida y vuelta comprobada, es el tipo de cosa con la que un asistente puede trabajar bien, y con la que tú puedes revisar lo que ha hecho antes de aceptarlo.

Cierre de la serie

Con esta entrega termina «Por dentro de KapyCAD 2». Si llegas ahora, este es el recorrido completo:

1. Cómo se prueba un CAD: cómo cazamos el error que no se ve, la cara que se mueve 0,2 mm sin avisar.
2. Actualizar sin miedo: tus archivos se abren igual: un formato que cambia y piezas que se siguen abriendo igual.
3. Nuestro propio OpenCascade: el kernel de geometría, compilado y mantenido por nosotros.
4. Un núcleo en Rust para todo el documento: donde vivirá el modelo entero en KapyCAD 2.
5. Por qué escribimos nuestro propio solver de restricciones: dejar de parchear y hacer un solver de croquis a medida.
6. Arrastrar sin que el croquis salte: cómo el croquis seguirá al cursor y no saltará al soltar.
7. Cuál de tus restricciones sobra: un diagnóstico que nombra solo las restricciones que sobran o chocan.

La octava es esta: kapycode, tu modelo como texto.