Kandi
=====

Versin: 3.1
Autor:   Pedro Reina
Fecha:   D.28.6.1998


Objetivo del programa
---------------------

Generar y modificar imgenes en 16 tonos de gris usando frmulas matemticas
para la definicin de los colores. Las imgenes se pueden grabar y leer como
ficheros TIFF.


Requisitos del programa
-----------------------

El programa puede funcionar en cualquier PC que disponga de tarjeta grfica
VGA.


Arranque del programa
---------------------

Basta teclear

Kandi

Opcionalmente, se puede invocar el programa escribiendo como parmetro el
nombre del fichero de configuracin que se desea usar. Si se deseara usar el
fichero de nombre "Ejemplo", habra que teclear

Kandi Ejemplo


Lectura de la configuracin
---------------------------

Si se invoca Kandi sin especificar ninguna configuracin, se busca el fichero
Kandi.cnf en el directorio actual, por si existiera.


Uso del programa
----------------

El programa presenta un men principal con cinco opciones:

La opcin Salida permite concluir el programa. Tambin se puede salir del
programa pulsando ESC en el men principal.

La opcin Explica presenta unas indicaciones sobre el uso del programa y la
forma de contactar con el autor.

La opcin Fichero es la que permite leer y grabar imgenes. Se encuentran
cuatro opciones:

    La opcin Lee busca en el directorio seleccionado todos los ficheros que
    coincidan con la mscara que est escrita en ese momento y que tengan la
    extensin correcta. Aparece un men con todos los archivos encontrados. Se
    selecciona el que se desea leer o se pulsa ESC para anular el proceso.
    Opcionalmente, los ficheros pueden aparecer en orden alfabtico si en el
    men "Opciones" se selecciona "Orden" S.

    La opcin Grabar permite almacenar en un fichero la imagen que est en
    memoria en ese momento.

    La opcin Directorio permite especificar el directorio donde se buscarn
    los ficheros. Si se deja en blanco, se toma como directorio el actual.

    La opcin Mscara permite escribir la mscara que se usar para buscar
    ficheros. Se pueden usar dos caracteres especiales: el asterisco (*), que
    significa cualquier cantidad de caracteres y la interrogacin (?), que
    significa uno o ningn carcter.

    La opcin Extensin permite especificar la extensin de los ficheros. En
    principio, lo lgico es usar slo extensin TIF, que es la de los ficheros
    TIFF.

La opcin Imagen es la que dirige la creacin y modificacin de las imgenes.
Se dispone de un men con siete opciones que se explican a continuacin:

    En la opcin Frmula se pide la frmula que se va a usar para generar la
    imagen. La frmula se aplicar a todos los puntos de la zona activa. La
    frmula actuar sobre una calculadora con notacin polaca inversa (RPN),
    como las de gama alta de Hewlett-Packard, en la que ya estarn introducidas
    la columna y la fila del punto que se va a calcular. El valor resultante de
    la frmula se utiliza para asignar un nivel de gris de 0 a 15 tomando
    mdulo 16. En la seccin "La calculadora" de este manual se explica con ms
    detalle cmo usar esta calculadora.

    La opcin Generar aplica la frmula a cada punto de la zona activa,
    calculando efectivamente la imagen.

    La opcin Mostrar presenta en pantalla la imagen completa que est en
    memoria en ese momento.

    La opcion Tamao define las dimensiones de la imagen. Si se usa esta
    opcin, se borra la imagen en memoria.

    La opcin Zona define la parte de la imagen a la que se aplicar la
    frmula. Esta opcin permite crear imgenes complejas usando diferentes
    frmulas para diferentes zonas.

    La opcin Invertir invierte los colores de la imagen en memoria. El blanco
    pasa a negro, el negro a blanco y el resto de tonos de gris cambia
    adecuadamente.

    La opcin Borrar borra la imagen en memoria.

La opcin Opciones se usa para especificar dos parmetros del programa:

    La opcin Sonido permite tener seales acsticas durante el programa.

    La opcin Orden determina que la lista de ficheros que aparece en la opcin
    "Lee" del men "Fichero" est en orden alfabtico o aparezcan tal como se
    encuentran en el directorio.


La calculadora
--------------

Si ya se ha usado alguna vez una calculadora con RPN, ser muy sencillo hacer
buen uso de la calculadora de este programa. Si no, aqu se muestra cmo
hacerlo.

Una calculadora RPN dispone de una "pila" en la que se van almacenando nmeros.
La pila de la calculadora de Kandi tiene una capacidad de 5 nmeros enteros de
32 bits con signo. La pila se va llenando de abajo arriba, y si sobran nmeros
por la parte superior, simplemente se desprecian.

Los nmeros se introducen en la pila simplemente escribindolos separados por
espacios. Cuando entra un nuevo nmero, empuja hacia arriba los que ya estaban.

Cuando se escribe una operacin, se realiza entre los nmeros de los dos
niveles ms bajos, que desaparecen de la pila; el resultado queda en el nivel
ms bajo. Las operaciones admitidas son las cuatro aritmticas bsicas (+, -, *
y /) y la operacin "aleatorio", representada por "ALE", que da un nmero
entero comprendido entre los dos dados, o igual a uno de ellos.

Se pueden usar funciones que actan sobre el nmero del nivel ms bajo,
sustituyndolo por el resultado. Hay dos: cuadrado ("CDR") y cubo ("CUB").

Hay dos rdenes disponibles para manipular la pila: intercambio ("INT"), que
intercambia entre s los nmeros de los dos niveles ms bajos y duplicado
("DUP"), que duplica el nmero del nivel ms bajo en el inmediatamente
superior, deplazando hacia arriba toda la pila.

Las funciones representadas por tres letras se pueden introducir en maysculas
o en minsculas.

Los siguientes ejemplos explican estas operaciones:

Notacin algebraica          Notacin RPN             Resultado

4+5                          4 5 +                    9
-8*(-3)                      -8 -3 *                  24
4*(5+7)                      4 5 7 + *                48
(5+6)/2                      5 6 + 2 /                5
5*3^2                        5 3 cdr *                45

Cuando se utiliza la calculadora para asignar un color a un punto, la columna
se encuentra en el nivel ms bajo y la fila en el siguiente superior. Por
tanto, hay que escribir las operaciones que habr que realizar con ellas.

En los siguientes ejemplos la fila se representa por "f" y la columna por "c":

Notacin algebraica          Notacin RPN

3*f+4c                       4 * int 3 * +
f^2-c^3                      cub int cdr int -
f+c+Ale(0,1)                 0 1 ale + +


El fichero de configuracin
---------------------------

Cuando se invoca Kandi se puede cargar un fichero de configuracin para definir
algunos parmetros del programa.

Los ficheros de configuracin son simples ficheros de texto que se pueden crear
y modificar con cualquier editor de texto. Se pueden introducir cuantos
comentarios se desee. Se considera comentario toda lnea que comience con el
carcter '*' y toda la parte de una lnea a partir de la doble barra ("//").
Las lneas en blanco se ignoran.

Para configurar un parmetro hay que introducir una lnea en el fichero que
tenga como primera palabra el indicador de lo que se quiere configurar y a
continuacin el valor o valores que se desean dar. Se pueden introducir en
cualquier orden.

Para ayudar al usuario a crear su propio fichero de configuracin se incluye
uno de ejemplo, llamado Kandi.cnf.

A continuacin se describen las posibles entradas:

Sonido

Escribiendo "S" o "No", se especifica si el programa debe comenzar con el
sonido conectado o no. Si este parmetro no se incluye el programa toma por
defecto el valor "No".

Ordenar

Escribiendo "S" o "No", se especifica si la lista de ficheros que aparece en
la opcin "Lee" del men "Fichero" debe verse en orden alfabtico o tal como se
encuentran en el directorio. Si este parmetro no se incluye el programa toma
por defecto el valor "No".