Argumentos del programa

Orden de coordenadas

{lon_lat, lat_lon}

El usuario debe especificar si el orden de las coordenadas introducidas es (Longitud, Latitud) o (Latitud, Longitud), ya que no hay unanimidad al respecto. Por ejemplo, el estándar EPSG:4326 (European Petroleum Survey Group) utiliza (Latitud, Longitud), pero en KML es al revés: kmlreference

NOTA: si al cargar el fichero KML los placemarks aparecen:

• En fila y con un fondo gris con Google Maps.
• En el Polo Norte con Google Earth.

seguramente hayamos cometido un error al seleccionar el orden de coordenadas.

Mezcla

--path_ends_placemark_merge
--merge_limit FLOAT (en metros. Utilizar punto y no coma como separador decimal)

Se junta cada extremo del path con placemarks cercanos si la distancia entre ellos es menor que --merge_limit. Para ello, se recoloca el placemark en el extremo del path. La idea detrás de esta opción es que el creador de las coordenadas quería, en efecto, situar uno exactamente encima del otro, pero, por imprecisiones de la interfaz gráfica del programa usado, ha quedado involuntariamente una pequeña distancia entre ambos.

Veamos el efecto sin, y con, mezcla.

PyMappu añade siempre puntos al principio (en verde) y final (en amarillo) del path. Si no especificamos mezcla, permanecen con sus nombres por defecto: "Path Start" y "Path End". En caso contrario, y si se cumple la condición de merge_limit, absorben el nombre del placemark con el que hayamos juntado.

--merge_limit tiene un valor por defecto de 10 metros. Podemos especificar otro. Si utilizamos decimales, emplear el punto y no la coma como separador decimal, o de lo contrario saltará un error como éste:

__main__.py: error: argument --merge_limit: invalid float value: '10,3'

Entrada y salida

-i INPUT_FILE, --input_file INPUT_FILE
-o OUTPUT_FILE, --output_file OUTPUT_FILE

PyMappu da total libertad de combinaciones de entrada y salida: podemos emplear stdin y stdout, stdin y salida fichero, entrada fichero y stdout, y entrada fichero y salida fichero. No permito mostrar el resultado del programa por stdout y fichero a la vez. No hay ninguna razón técnica que lo impida, pero supongo que si un usuario especifica la salida por fichero, no quiere ver la misma salida por stdout, y viceversa.

Codificación

-ienc INPUT_FILE_ENCODING, --input_file_encoding INPUT_FILE_ENCODING
--no_terminal_stdout_encoding NO_TERMINAL_STDOUT_ENCODING

En este programa el soporte Unicode es importante porque el nombre o la descripción de un lugar pueden no estar en el alfabeto romano (alfabeto latino). Por ejemplo: el griego, el (abyad) hebreo, el cirílico, el (àksŏn thai) tailandés, los kanji japoneses y hanzi chinos, etcétera.

Si la entrada es un fichero, debemos especificar la codificación de éste. Puede que esto suponga un incordio para el usuario, pero lo veo necesario por lo que se comenta en joelonsoftware.com:

It does not make sense to have a string without knowing what encoding it uses. If you have a string, in memory, in a
file, or in an email message, you have to know what encoding it is in or you cannot interpret it or display it to
users correctly.

Los exploradores web, en ausencia de información sobre codificación, utilizan análisis de frecuencias para "adivinar" el idioma y la codificación asociada a éste, pero es complicado, y no siempre no funciona bien.

Una opción un tanto "extraña" es "--no_terminal_stdout_encoding". Con ella elegimos la codificación cuando stdout no sea una terminal (de no especificarse, Python utiliza sys.getdefaultencoding()). Por ejemplo, al redireccionar a fichero mediante "programa > salida.txt". Este caso sería un poco tonto para PyMappu, puesto que ya tenemos otra opción específica para "-o" para ello. Otro ejemplo más útil sería el del pipeline, por el que el stdout de un programa alimenta al stdin de otro: "un_programa | otro_programa". En este caso deberíamos saber qué codificaciones admite "otro_programa". Para terminar, una advertencia: la codificación de salida no debería ser más restrictiva que la de entrada, o de lo contrario se convertirá a "código HTML" (numeric character reference).

La opción es sólo para stdout sin terminal y no para stdout en general. Esto es así porque las terminales ya dan información sobre su codificación a través de sys.stdout.encoding.

NOTA: El intérprete de comandos de Windows (Windows Command Processor, cmd.exe) no puede mostrar Unicode con programas implementados en Python, aunque cambiemos el code page a 65001 (utf-8) y seleccionemos una fuente que cubra el rango de caraceres deseado. Esto es debido al uso interno del stdio de C en Python. Para más información, consultar getting-python-to-print-in-utf8-on-windows-xp-with-the-console.

Las opciones --output_file y --no_terminal_stdout_encoding no pueden aparecer juntas, ya que no permito mostrar el resultado del programa por stdout y fichero a la vez (--no_terminal_stdout_encoding sólo tiene efecto cuando se utiliza stdout). No hay ninguna razón técnica que lo impida, pero supongo que si un usuario especifica la salida por fichero, no quiere ver la misma salida por stdout, y viceversa.

Ejemplo de ejecución

D:\>pymappu-windows -i input-instructions.txt -ienc utf-8 -o mymap lat_lon
--path_ends_placemark_merge

Warning: --path_ends_placemark_merge is present but --merge_limit is absent.
Assigning default value of 10.000000 meters.
Expr rule correctly parsed

En entornos Unix utilizaríamos pymappu-unix en lugar de pymappu-windows.

Ayuda

-h, --help

El programa muestra la siguiente ayuda con la opción -h, --help:

usage: pymappu [-h] [--path_ends_placemark_merge] [--merge_limit MERGE_LIMIT]
               [--icon_url ICON_URL ICON_URL ICON_URL ICON_URL]
               [-i INPUT_FILE] [-ienc INPUT_FILE_ENCODING]
               [-o OUTPUT_FILE | --no_terminal_stdout_encoding NO_TERMINAL_STDOUT_ENCODING]
               {lon_lat,lat_lon}

Generate KML output from coordinate input expressions.
See the accompanying grammar file included in the documentation
for coordinate expression definition.

Input examples (attractions are the most interesting places
and additions secondary ones):

	putAttraction (
		( "optionalName1" "optionalDescription1" (1.1, 2.2) )
		( (3.3, 4.4) )
		( "youCan\"EscapeQuotes" (5.5, 6.6) )
	)
	putAddition (
		( "additionName1" (1.1, 2.2) )
		( "additionName2" (3.3, 4.4) )
	)
	drawPath (
		"itineraryName" (1.1, 2.2) (3.3, 4.4) (5.5, 6.6)
	)

Note: place/path descriptions are not allowed without a place/path name (description will be taken as name)

positional arguments:
  {lon_lat,lat_lon}     Coordinates order options are: "lon_lat" for
                        (Longitude, Latitude) and "lat_lon" for (Latitude,
                        Longitude)

optional arguments:
  -h, --help            show this help message and exit
  --path_ends_placemark_merge
                        The path ends (beginning, end, or both) will be merged
                        with a nearby placemark if it's closer than
                        MERGE_LIMIT
  --merge_limit MERGE_LIMIT
                        See --path_ends_placemark_merge. Float value, in
                        meters. Use dot (not comma) as decimal separator.
  --icon_url ICON_URL ICON_URL ICON_URL ICON_URL
                        Specify 4 Icon Image URLs for PATH_START_POINT,
                        PATH_END_POINT, ATTRACTION_POINT and ADDITION_POINT.
                        If not specified, default URLs take place, but keep in
                        mind the Internet resources these point to may become
                        unavailable in the future.
  -i INPUT_FILE, --input_file INPUT_FILE
                        File to parse. If not specified, stdin is used.
  -ienc INPUT_FILE_ENCODING, --input_file_encoding INPUT_FILE_ENCODING
                        File input encoding. Mandatory if --input_file is
                        specified.
  -o OUTPUT_FILE, --output_file OUTPUT_FILE
                        Resulting KML file. If not specified, stdout is used.
                        Not allowed with argument
                        --no_terminal_stdout_encoding
                        (--no_terminal_stdout_encoding is just for stdout
                        case, and the program doesn't let you do both stdout
                        and file output).
  --no_terminal_stdout_encoding NO_TERMINAL_STDOUT_ENCODING
                        Encoding to use when stdout is not a terminal:
                        redirection to file and pipelines. Redirection to file
                        is not interesting because there's already an spefic
                        -o option for that. Pipelines make more sense. Not
                        allowed with argument -o/--output_file
                        (--no_terminal_stdout_encoding is just for stdout
                        case, and the program doesn't let you do both stdout
                        and file output).