Documentación de Celestia

 
  4. CELX SCRIPTS  
  4.8. Objetos y métodos de la api de celx  
 

En este apartado se detallan las clases que se pueden utilizar en los scripts CELX para interactuar con Celestia y los métodos correspondientes a cada una de ellas. Los parámetros opcionales de algunos métodos serán encerrados entre corchetes ([]). Al comienzo del script, el único objeto relacionado con el simulador disponible es celestia, por lo que será necesario llamar a sus métodos para crear objetos pertenecientes a otras clases.

Los objetos disponibles en CELX son:

celestia: Se trata de un objeto predefinido que da acceso a toda la funcionalidad de Celestia disponible en CELX, ya sea a través de sus propios métodos o permitiéndonos crear otros objetos con funciones adicionales. Sus métodos se detallan a continuación:

  • print (string text[, number duration, number horig, number vorig, number hoffset, number voffset]): Imprime el texto del primer parámetro en pantalla. El segundo parámetro indica el número de segundos que se muestra el texto (5 por defecto), el tercer y el quinto parámetro permiten fijar el origen horizontal del texto (-1 izquierda, 0 centro y 1 derecha) y su desplazamiento en esta dirección mientras que el cuarto y el sexto parámetro estableces el origen vertical (-1 abajo, 0 centro y 1 arriba) y su desplazamiento en vertical.
  • flash (string text[, number duration]): Muestra el texto del primer parámetro en el simulador durante el tiempo indicado en el segundo parámetro (5 por defecto).
  • show (string renderflag): Habilita la visualización de uno o varios elementos (como orbits, grid o atmospheres). Se pueden activar múltiples elementos pasando al método varios parámetros con los diferentes nombres.
  • hide (string renderflag): Deshabilita la visualización de uno o varios elementos (método opuesto anterior).
  • table getrenderflags (): Devuelve una tabla con todos los elementos cuya visualización se puede activar o desactivar como claves y un valor booleano indicando si están habilitados o deshabilitados.
  • setrenderflags (table renderflags): Habilita o deshabilita la visualización de determinados elementos según el contenido de la tabla que se le pase como parámetro. Esta tabla tiene el mismo formato que la del método anterior.
  • showlabel (string labelflag): Activa el tipo de etiquetas que se le indique por parámetro (como planets, moons o comets).
  • hidelabel (string labelflag): Desactiva el tipo de etiquetas que se le indique por parámetro (opuesto al método anterior).
  • table getlabelflags (): Devuelve una tabla con todos los tipos de etiquetas como claves y un valor booleano indicando si están activadas o desactivadas (similar a getrenderflags).
  • setlabelflags (table labelflags): Activa o desactiva el etiquetado de determinados elementos según el contenido de la tabla que se le pase como parámetro. Esta tabla tiene el mismo formato que la del método anterior.
  • table getorbitflags (): Devuelve una tabla con todos los tipos de órbitas como claves y un valor booleano indicando si están activadas o desactivadas.
  • setorbitflags (table orbitflags): Activa o desactiva la visualización de determinadas órbitas según el contenido de la tabla que se le pase como parámetro. Esta tabla tiene el mismo formato que la del método anterior.
  • number getambient (): Devuelve el nivel de luz ambiental actual.
  • setambient (number ambient): Permite fijar el nivel de luz ambiental (su parámetro debe ser un número entre 0 y 1).
  • number getfaintestvisible (): Devuelve un valor indicando la magnitud del elemento más débil que todavía se dibuja en el simulador (45º si la opción de auto-magnitud está activada).
  • setfaintestvisible (number faintest): Fija la magnitud del elemento más débil que dibujará Celestia (Se mantendrá en 45º si está activada la opción auto-magnitud).
  • number getminororbitsize (): Devuelve el tamaño mínimo de una órbita (en pixels) para que sea dibujada por el simulador.
  • setminororbitsize (number faintest): Establece el tamaño mínimo de una órbita (en pixels) para que sea pintada en pantalla.
  • number getstardistancelimit (): Devuelve la máxima distancia en la que se seguirán dibujando las estrellas en el simulador.
  • setstardistancelimit (number distance): Fija la máxima distancia en la que las estrellas serán todavía visibles en Celestia.
  • number getminfeaturesize (): Devuelve el tamaño mínimo de las etiquetas de las localizaciones.
  • setminfeaturesize (number size): Establece el tamaño mínimo para las etiquetas de las localizaciones.
  • string getstarstyle (): Devuelve el estilo con que se dibujan las estrellas (fuzzy, disc o point).
  • setstarstyle (string starstyle): Permite definir la forma en que se dibujan las estrellas en el simulador (fuzzy, disc o point).
  • object find (string name): Devuelve el objeto cuyo nombre se le pasa como parámetro.
  • object getselection (): Devuelve el objeto que esté seleccionado actualmente.
  • select (object o): Selecciona el objeto que se le pasa como parámetro.
  • mark (object o): Crea un marcador al objeto indicado.
  • unmark (object o): Borra un marcador existente al objeto que se le pasa como parámetro.
  • unmarkall (): Elimina todos los marcadores existentes.
  • number gettime (): Devuelve el tiempo actual en la simulación en julian days (número de días transcurridos desde la media noche del 1 de Enero del 4713 antes de Cristo).
  • settime (number time): Fija el tiempo de la simulación pasándole un número con la fecha en julian days.
  • number gettimescale (): Devuelve la escala actual del tiempo (número de segundos de la simulación equivalentes a un segundo real).
  • settime (number timescale): Establece la escala de tiempo de la simulación (número de segundos de la simulación equivalentes a un segundo real).
  • number getscripttime (): Devuelve el número de segundos que realmente han transcurrido desde que comenzó la ejecución del script.
  • number getstartcount (): Devuelve el número de estrellas en el catálogo de estrellas que se esté utilizando actualmente en el simuldor.
  • object getstar (number index_number): Devuelve la estrella cuyo índice en el catálogo se corresponda con el número indicado.
  • observer getobserver (): Devuelve un objeto de tipo observer con la información relativa a la vista actual.
  • table getobservers (): Devuelve una lista de objetos observer correspondientes a cada una de las vistas que se haya utilizado.
  • number tojulianday (number year, number month, number day, number hour, number minute, number seconds): Convierte la fecha y hora que se le pasan como parámetros (año, mes, día, hora, minuto y segundos) a su correspondiente valor en julian days.
  • table fromjulianday (number jd): Convierte un tiempo expresado en julian days en una tabla equivalente con los índices year, month, day, hour, minute y second (año, mes, día, hora, minuto y segundos).
  • x, y getscreendimension (): Devuelve el alto y el ancho de la ventana de Celestia.
  • vector newvector (number x, number y, number z): Crea un vector con las tres componentes que se le pasan como parámetro. La unidad en todos los casos son micro años luz.
  • position newposition (number x, number y, number z): Crea un nuevo objeto position con los tres parámetros que se le pasan. La unidad en todos los casos son micro años luz. La unidad en todos los casos son micro años luz.
  • position newposition (string x, string y, string z): Crea un nuevo objeto position a partir de tres valores codificados en base 64 (formato utilizado en cel: //URL).
  • rotation newrotation (vector axis, angle w): Crea un objeto rotation que utiliza como eje de rotación el vector del primer parámetro y gira el ángulo indicado en el segundo parámetro.
  • rotation newrotation (number w,number x, number y, number z): Crea un objeto rotation con el vector formado por las componentes x,y y z, y con el valor indicado en w.
  • frame newframe (string coordsysname[, object ref, object target): Crea un nuevo sistema de referencia (objeto frame) indicándole el tipo en el primer parámetro (debe ser universal, ecliptic, equatorial, planetographic, observer, lock o chase). Será necesario especificar en el segundo parámetro el objeto de referencia (salvo con el tipo universal) y solamente para el tipolock se deberá establecer el objetivo como tercer parámetro del método.
  • requestkeyboard (boolean enable): Activa o desactiva las entradas por teclado según el valor de su único parámetro. Se le dará valor true si se quiere activar la entrada de teclado y valor false para que Celestia maneje las entradas de teclado.
  • requestsystemaccess (): Solicita permiso para acceder a las librería io y os de LUA, que permiten la escritura de ficheros y la ejecución de programas.
  • string getscriptpath (): Devuelve una cadena con la ruta al script que se está ejecutando.
  • boolean getscriptpath (string filetype, string name): Toma una captura de pantalla del simulador del tipo especificado en el primer parámetro (png o jpg) y la almacena en disco con un nombre que incluye el segundo parámetro, devolviendo true si la operación se realiza con éxito. Las capturas se guardan en el directorio indicado en la opción ScriptScreenshotDirectory dentro del fichero de configuración celestia.cfg.
  • celscript createcelscript (string CELsource): Crea un objeto de tipo celscript a partir del contenido la cadena de texto que se le pasa como parámetro. Si la cadena no contiene un script de tipo CEL válido, el método producirá un error. El objeto devuelto se puede utilizar para ejecutar un script CEL dentro de un script CELX.

observer: Este objeto se utiliza para acceder a las propiedades específicas de una vista del simulador, como el sistema de referencia, el punto de vista o el tipo de seguimiento que se realiza a un cuerpo celeste. Es posible que los objetos de este tipo sean destruidos por el usuario y se conviertan en objetos inválidos al intentar utilizarlos, por lo que es conveniente realizarcomparaciones previas con otros objetos del mismo tipo para garantizar su validez (estas comparaciones se pueden realizar con el operador “==”). Los métodos que proporciona este objeto son:

  • goto (object/position target[, number duration, number start_inter,number end_inter]): Desplaza la cámara a la posición o al objeto especificado en el primer parámetro (las posiciones son relativas al sistema de coordenadas actual). El segundo parámetro indicará opcionalmente la duración del desplazamiento (5 segundos por defecto).
  • goto (table gotoparams): Desplaza la cámara al lugar indicado, utilizando para ello la información de la tabla que se le pasa como parámetro. La tabla incluye las claves duration (duración), from (posición origen), to (posición destino), inicialOrientation (orientación en el origen), finalOrientation (orientación en el destino), startInterpolation, endInterpolation y accelTime. En este método las posiciones son especificadas siempre en el sistema de coordenadas universal.
  • goto (object target[, number longitude, number latitude, number distance, number duration]): Desplaza la cámara al objeto indicado en el primer parámetro sobre el punto que tenga la longitud y la latitud señaladas en el segundo y el tercer parámetro (ambas 0 por defecto). El cuarto parámetro permite indicar la distancia al centro del objeto (5 veces el radio del objeto por defecto) mientras que el último parámetro especifica la duración del desplazamiento (5 segundos por defecto).
  • gotolocation (position target[, number duration]): Desplaza la cámara a la posición especificada en el primer parámetro (en el sistema de coordenadas actual) en el tiempo indicado en el segundo parámetro (5 segundos por defecto).
  • gotolocation (object target[, number distance, number duration]): Desplaza la cámara al objeto señalado en el primer parámetro en el tiempo indicado en el último parámetro (5 segundos por defecto). La cámara se quedará a una distancia del objeto especificada en el segundo parámetro en Km. (20000 por defecto).
  • gotosurface (object target[, number duration]): Desplaza la cámara a la superficie del objeto especificado en el primer parámetro en el tiempo indicado en el segundo parámetro (5 segundos por defecto).
  • center (object target[, number duration]): Gira la cámara hasta centrar en la vista del simulador el objeto indicado en el primer parámetro, tardándose el número de segundos indicado en el segundo parámetro en realizar la acción (5 segundos por defecto).
  • centerorbit (object target[, number duration]): Orbita el objeto de referencia en el sistema de coordenadas actual hasta que el objeto especificado en el primer parámetro quede centrado, tardándose el número de segundos indicado en el segundo parámetro en realizar la acción (5 segundos por defecto).
  • boolean traveling (): Devuelve true si actualmente hay un comando goto o center en curso.
  • cancelgoto (): Para cualquier comando goto o center que esté en curso actualmente.
  • follow (object target): Activa el modo follow respecto al objeto que se le pasa como parámetro.
  • synchronous (object target): Activa el modo sync orbit respecto al objeto que se le pasa como parámetro.
  • chase (object target): Activa el modo chase respecto al objeto que se le pasa como parámetro.
  • lock (object target): Activa el modo lock con el objeto que se le pasa como parámetro como objetivo y el objeto que se tenga seleccionado como referencia.
  • track (object target): Activa el seguimiento del objeto que se le pasa como parámetro.
  • setposition (position pos): Fija la posición en el simulador a aquella que se pase como parámetro.
  • position getposition (): Devuelve la posición actual en el sistema de referencia universal.
  • setorientation (rotation rot): Fija la orientación en el simulador a aquella que se pase como parámetro.
  • rotation getrotation (): Devuelve la orientación actual del observador en el sistema de referencia universal.
  • rotate (rotation rot): Gira la orientación actual del observador acorde con el valor que se le pase como parámetro.
  • lookat (position from, position to, vector up): Fija la orientación tomando como punto de observación el primer parámetro, como objetivo el segundo parámetro y definiendo en el último parámetro la dirección del eje vertical imaginario que habría sobre el observador (no puede ser paralelo al vector formado por las dos posiciones de los dos primeros parámetros).
  • number gettime (): Devuelve el tiempo correspondiente al objeto observer en julian days.
  • number getspeed (): Devuelve la velocidad correspondiente al objeto observer en micro años luz.
  • setspeed (number speed): Fija la velocidad a la que se le pase como parámetro (en micro años luz).
  • string getsurface (): Devuelve una cadena de texto describiendo la apariencia actual.
  • setsurface (string name): Fija la apariencia actual a aquella que se le pasa como parámetro.
  • number getfov (): Devuelve el campo de visión (FOV) actual en radianes.
  • setframe (number fov): Fija el campo de visión (FOV) al valor en radianes que se le pasa como parámetro.
  • frame getframe (): Devuelve el marco de referencia del observador actual.
  • setframe (frame f): Fija el marco de referencia a aquel que se le pase como parámetro.
  • splitview (sring splitdirection[, number splitpos]): Divide la vista actual del observador en dos. El primer parámetro indica si la división se hace horizontalmente (“h”) o verticalmente (“v”) mientras que el segundo parámetro especifica el lugar por el que se divide (la mitad, 0.5, por defecto).
  • deleteview (): Elimina la vista correspondiente al observador actual siempre y cuando quede al menos una vista más en el simulador. El objeto observer no debe volver a utilizarse después de llamar a este método.
  • singleview (): Hace que la vista correspondiente al observador actual sea la única en el simulador.
  • boolean isvalid (): Devuelve true si el objeto observer que lo llama sigue siendo válido (puede dejar de ser válido al llamar a alguno de los dos métodos anteriores o por alguna acción del usuario).
  • table getlocationflags (): Devuelve una tabla indicando que tipo de localizaciones están activas. Las claves de esta tabla son city, observatory, landingsite, crater, vallis, mons, planum, chasma, patera, mare, rupes, tessera, regio, chaos, terra, astrum, corona, dorsum, fossa, catena, mensa, rima, undae, reticulum, planitia, linea, fluctus, farrum y other.
  • setlocationflags (table locationflags): Fija las localizaciones activas e inactivas según el contenido de la tabla que se pasa como parámetro (con el mismo formato que la tabla anterior).

object: Este tipo de objeto no hace referencia a un objeto general como ocurre en otros lenguajes de programación (Ej.: Java), sino que se refiere a un objeto de Celestia (un planeta, una luna, una estrella,…). Sus métodos son:

  • numberradius (): Devuelve el radio del objeto actual en kilómetros.
  • stringtype (): Devuelve el tipo al que pertenece el objeto actual. Los posibles valores retornados son planet, moon, asteroid, comet, spacecraft, star, invisible, unknown, deepsky, location o null.
  • stringspectraltype (): Si el objeto actual es una estrella, el método devuelve una cadena describiendo el tipo de espectro. En otro caso devuelve nil.
  • numberabsmag (): Si el objeto actual es una estrella, el método devuelve la magnitud absoluta de la misma. En otro caso devuelve nil.
  • stringname (): Devuelve el nombre del objeto actual.
  • table getinfo (): Devuelve una tabla con la información disponible para el objeto actual. El contenido varía según el tipo de objeto.
  • mark (string color, string symbolname[, number size]): Crea un marcador al objeto actual del color que se especifica en el primer parámetro (pueden usarse algunos nombres de colores predefinidos o una cadena del tipo “#hhhhhh” como las usadas en HTML, donde h es un número hexadecimal) y utilizando como marcador el símbolo indicado en el segundo parámetro (puede ser diamond, triangle, square, plus o x). Opcionalmente se puede indicar el tamaño del marcador (10 por defecto).
  • unmark (): Elimina un marcador al objeto actual.
  • position getposition (number time): Devuelve la posición del objeto actual en el instante de tiempo que se pasa como parámetro.
  • table getchildren (): Devuelve una tabla que contiene todos los objetos hijos del objeto actual (Ej.: Las lunas de un planeta).
  • preloadtexture (): Precarga la textura del objeto actual desde disco. Esto puede ser útil para reducir los retardos al aproximarse a un objeto.

position: Este objeto contiene las coordenadas exactas de un punto en el espacio. Esta posición es relativa a un sistema de coordenadas específico, por lo que es posible que sea necesario realizar una conversión desde o hacia el sistema universal. Los métodos que posee este objeto son:

  • position getposition (): Devuelve la posición actual en el sistema de referencia universal.
  • position addvector (vector v): Devuelve la posición resultado de sumarle a la posición actual el vector que se pasa como parámetro. Se puede obtener el mismo resultado utilizando el operador + con una posición y un vector directamente.
  • vector vectorto (position target): Devuelve un vector que va desde la posición actual a la que se pasa como parámetro.
  • numberdistanceto (position target): Devuelve, en kilómetros, la distancia existente entre la posición actual y la que se pasa como parámetro.
  • rotation orientationto (position target): Devuelve un objeto rotation que apunte a la posición que se pasa como parámetro.
  • numbergetx (): Devuelve la coordenada x de la posición (se puede acceder directamente utilizando la expresión position.x).
  • numbergety (): Devuelve la coordenada y de la posición (se puede acceder directamente utilizando la expresión position.y).
  • numbergetz (): Devuelve la coordenada x de la posición (se puede acceder directamente utilizando la expresión position.z).

vector: Este objeto contiene un vector que apunta desde una posición hasta otra posición. La unidad de medida utilizada para estos vectores son micro años luz. Los métodos disponibles son:

  • numbergetx (): Devuelve la componente x del vector (se puede acceder directamente utilizando la expresión vector.x).
  • numbergety (): Devuelve la componente y del vector (se puede acceder directamente utilizando la expresión vector.y).
  • numbergetz (): Devuelve la componente z del vector (se puede acceder directamente utilizando la expresión vector.z).
  • vectornormalize (): Devuelve un vector que apunte en la misma dirección que el actual pero con longitud 1. Se debe tener cuidado porque si se utiliza con vectores muy pequeños el resultado de la llamada al método no está definido.
  • numberlength (): Devuelve el tamaño del vector.

rotation: Son objetos formados por cuatro componentes (x, y, z y w) que representan la orientación en el espacio. Se puede acceder directamente a cada una de estas componentes con expresiones como rotation.x (para el caso de la componente x). Los métodos de este objeto son:

  • vectorimag (): Devuelve las componentes x, yz del objeto rotation actual como un vector.
  • numberreal (): Devuelve la componente w del objeto.
  • vectortransform (vector v): Aplica el objeto rotation actual al vector que se pasa como parámetro y devuelve el vector resultante.
  • setaxisangle (vector v, number w): Fija el eje y el ángulo del objeto rotation actual a los valores que se le pasan como primer y segundo parámetro al método.
  • rotation slerp (rotation rot, number t): Devuelve una interpolación del objeto rotation actual y del que se pasa como parámetro, indicando el segundo parámetro la importancia de ambas rotaciones en la interpolación (valor entre 0 y 1, devolviéndose con 0 el objeto rotation actual y con 1 el que se pasa como parámetro).

frame: Este objeto representa el marco de referencia del observador. Los métodos de los que dispone son:

  • positionto (position pos[, number time]): Convierte la posición que se pasa en el primer parámetro del sistema de coordenadas universal al correspondiente al objeto actual, devolviendo la posición resultante. El segundo parámetro indica el tiempo que se utiliza para realizar la conversión, ya que hay que tener en cuenta que los marcos de referencia son relativos a objetos que están en movimiento (tiempo actual del simulador por defecto).
  • rotationto (rotation rot[, number time]): Convierte la rotación que se pasa en el primer parámetro del sistema de coordenadas universal al correspondiente al objeto actual, devolviendo la rotación resultante. El segundo parámetro especifica el tiempo que se utiliza para realizar la conversión (tiempo actual del simulador por defecto).
  • positionfrom (position pos[, number time]): Convierte la posición que se pasa en el primer parámetro del sistema de coordenadas correspondiente al objeto actual al sistema universal, devolviendo la posición resultante. El segundo parámetro indica el tiempo que se utiliza para realizar la conversión (tiempo actual del simulador por defecto).
  • rotationfrom (rotation rot[, number time]): Convierte la rotación que se pasa en el primer parámetro del sistema de coordenadas correspondiente al objeto actual al sistema universal, devolviendo la rotación resultante. El segundo parámetro especifica el tiempo que se utiliza para realizar la conversión (tiempo actual del simulador por defecto).
  • stringgetcoordinatesystem (): Devuelve el tipo de sistema de coordenadas correspondiente al objeto actual (ver en el método newframe() del objeto celestialos posibles valores de la cadena de texto devuelta).
  • numbergetrefobject (): Devuelve el objeto de referencia del marco actual o nil en caso de no existir.
  • numbergettargetobject (): Devuelve el objeto seleccionado como objetivo en el marco actual o nil si no lo hubiera.

celscript: Estos objetos se utilizan para ejecutar un script de tipo CEL dentro de un script CELX. Únicamente tiene un método que permite la ejecución del script:

  • booleantick (number dt): Ejecuta el script CEL durante la cantidad de segundos especificada en el parámetro. Devuelve true si el script todavía no ha terminado.
 
 
Índice general