Referencia del módulo lop

El módulo lop proporciona la interfaz de programación de aplicaciones (API) de Python para el visor y para los comandos del kit de desarrollo de software (SDK). Un guion importa el módulo con:

import lop

Cada llamada a lop.viewer y a lop.run_command se ejecuta en el hilo de la interfaz de Lot Of Points, y el guion espera a que termine. Las listas que devuelve lop.viewer son copias: el guion no recorre una colección que la aplicación pueda cambiar mientras tanto.

lop.run_command

lop.run_command(id) lanza la orden igual que su botón del ribbon y retorna sin esperar a que termine la orden: una orden interactiva (medir, seleccionar) queda esperando los clics del usuario, y un algoritmo sigue ejecutándose en segundo plano. La función no hace nada en estos casos:

• El identificador no existe.
• La orden necesita una nube abierta y no hay ninguna.
• El botón de la orden está desactivado en ese momento.

lop.viewer

lop.viewer es un objeto de .NET. Sus miembros tienen los nombres de .NET, en PascalCase. Las coordenadas del mundo son absolutas, en el sistema de la nube. Las coordenadas de pantalla están en píxeles físicos del área de dibujo, con el origen arriba a la izquierda.

Cámara y encuadre

Camera aplica la posición y la orientación al dibujo del siguiente fotograma, sin actualizar el estado de cámara que utilizan las herramientas de navegación: el siguiente clic, el siguiente giro de la rueda o la siguiente orden devuelven la vista a la posición de cámara que utilizan esas herramientas. Para cambiar la vista de forma estable, usa las órdenes de vista con lop.run_command (lop.view.top, lop.view.zoom-extents...).

Puntos bajo el cursor

LocatePoint y FirstPointInCylinder buscan entre los puntos que el visor tiene cargados en ese momento, no entre todos los puntos del archivo.

Selección y ediciones

eventCode es el código del evento en el registro; el historial traduce los códigos de selección y busca el nombre actual de los comandos. Las herramientas de selección de Lot Of Points usan "Sphere", "Cylinder", "Box" y "Polyline".

ExportEditedOriginal lee el archivo original entero. Desde un guion se ejecuta en el hilo de la interfaz, así que la interfaz no responde hasta que termina.

Imágenes esféricas

Estado visual

Las propiedades sin «lectura» se leen y se escriben. Lot Of Points no guarda en su configuración el estado visual que cambia un guion.

Otros miembros

Estos miembros los usan las herramientas interactivas de Lot Of Points:

Tipos

Tipos de .NET en Python

lop.viewer es un objeto de .NET que pythonnet muestra a Python. Los miembros conservan los tipos declarados en IViewer y las colecciones se adaptan mediante UiProxy:

Listas

• Una lista que devuelve lop.viewer (EditingHistory, EditableClouds, SphericalPhotos) admite for, índices (h[0]), la propiedad Count y list(...). Usa .Count o len(list(...)) para obtener el recuento.
• Un parámetro de lista (SelectByPolyline) no admite una lista de Python. Pasa un array de .NET:

import System
from Geometries import Point3D

vertices = System.Array[Point3D]([Point3D(0, 0, 0), Point3D(10, 0, 0)])

Tuplas

SizeInPixels, Stretch y ActualStretchRange devuelven tuplas de .NET (ValueTuple). Sus elementos se leen con Item1, Item2 e Item3.

Números, enumerados y None

• Un int de Python vale donde .NET espera un float, un byte o un entero sin signo.
• Las propiedades ColorAttribute y ColorRamp son enteros: asigna int(ColorAttribute.Classification) o el número.
• None vale donde .NET espera un objeto nulo (SelectedPoint = None, percent=None), y los métodos que pueden no encontrar nada devuelven None.

Errores

Un error de Lot Of Points dentro de una llamada llega al guion como una excepción. Si el guion no captura la excepción, el panel Salida muestra su tipo y su mensaje.

Comandos de Python

Declaración

@lop.command(id, name, *, existing_tab_id="", new_tab_title="",
             ribbon_section="", description="", parameters=(), icon="",
             requirements=0)
def command_function(host):
    ...

Exactamente uno de existing_tab_id y new_tab_title debe contener texto. Los identificadores de pestañas existentes son lop.tab.view, lop.tab.draw, lop.tab.edit y lop.tab.classification. ribbon_section determina la sección del plugin. icon es la ruta de una imagen PNG (Portable Network Graphics), relativa a la carpeta del guion. La imagen debe medir 32 × 32 píxeles y contener un dibujo negro sobre fondo transparente. El tamaño máximo del icono es 1.048.576 bytes. Un icono ilegible o inválido produce un aviso y el botón usa el icono predeterminado.

requirements combina lop.REQUIRES_OPEN_CLOUD, lop.REQUIRES_VISIBLE_CLOUD y lop.REQUIRES_EDITABLE_CLOUD. El programa habilita el botón y permite ejecutar el comando cuando se cumplen todos los requisitos declarados por el comando. Con 0, el botón no depende de esos requisitos. Una nube editable para este requisito necesita registro de ediciones e índices en el archivo original.

lop.Parameter(id, name, default, minimum, maximum, unit="",
              description="", settings_group=None, type="real")

type admite "real", "integer" y "boolean". settings_group agrupa controles en Configuración; host.parameter_value(id) obtiene el valor que el programa tomó al iniciar el comando.

lop.Host

El programa entrega el anfitrión a la función del comando y mantiene ese anfitrión válido durante la ejecución. Las llamadas que esperan puntos o teselas bloquean el hilo del comando y permiten que la interfaz atienda la navegación.

ask_point espera un clic sobre una nube visible y ofrece al filtro accept_point(point, cloud) los candidatos no borrados que estén a 0,05 unidades de la nube o menos del punto pulsado. El filtro recibe candidatos de todas las nubes abiertas, incluidas las ocultas, del más cercano al más lejano. El filtro devuelve True para aceptar y False para probar el candidato siguiente; una excepción del filtro se propaga al comando. Sin filtro, la función acepta el punto más cercano de las nubes visibles. Si ningún candidato sirve, el programa espera otro clic. La consulta respeta el aislamiento.

points_in_sphere admite un Point o una secuencia (x, y, z) como centro. El radio debe ser finito y mayor o igual que 0, en unidades de la nube. Con cloud_ids=None o una lista vacía, la función consulta las nubes visibles. Con identificadores explícitos, la función consulta las nubes indicadas que sigan abiertas, incluidas las ocultas. La consulta obtiene todo el detalle, aplica las ediciones y el aislamiento, y excluye los puntos borrados.

select_points recibe índices enteros de un resultado de points_in_sphere. Para convertir una máscara booleana en índices, usa numpy.flatnonzero(mask). La función rechaza índices negativos o mayores o iguales que el número de puntos. La selección permanece al terminar el comando para aplicar Borrar, Clasificar o Aislar. Una lista vacía de índices limpia la selección.

Point, Points y Cloud

Point contiene x, y, z, original_point_index, cloud_id, intensity, classification, return_number, number_of_returns, red, green y blue. El identificador de nube permanece válido mientras la nube siga abierta. El índice del original empieza en 0; lop.UNKNOWN_ORIGINAL_POINT_INDEX indica que la nube no conserva ese dato.

Points expone esas propiedades como columnas de numpy de solo lectura. len(points) devuelve el recuento y points[i] devuelve un Point. Las columnas comparten la memoria del resultado sin copiarla y conservan esa memoria mientras exista alguna columna o el objeto Points. Python libera el resultado sin una llamada explícita a release_points. points.complete vale False si algún nodo no se pudo leer o no llegó en el plazo de 2 minutos.

Cloud es una copia con cloud_id, name, original_path, visible, remote, editable, has_original_point_indices, extra_fields, box_min y box_max. Los límites son tuplas de tres coordenadas. La copia sigue siendo válida después de otra llamada a clouds, aunque el estado de la nube pueda cambiar.

TileOptions y process_tiles

lop.TileOptions(tile_core_side_length_cloud_units=0.0,
                tile_overlap_width_cloud_units=0.0, required_extra_fields=0,
                point_order=lop.ORDER_ORIGINAL_POINT_INDEX,
                concurrent=False, read_only=False,
                estimated_peak_bytes_per_point=0.0)

El lado del núcleo debe ser mayor que 0 y no superar 10.000.000 de unidades de la nube. El solape admite de 0 a 10.000.000 de unidades de la nube, ambos incluidos. El lado predeterminado 0 debe sustituirse antes de ejecutar process_tiles.

required_extra_fields combina lop.FIELD_GPS_TIME y lop.FIELD_POINT_SOURCE_ID: tiempo del sistema de posicionamiento global (GPS) e identificador de pasada. point_order admite lop.ORDER_ORIGINAL_POINT_INDEX y lop.ORDER_SOURCE_AND_GPS_TIME; el segundo orden exige los dos atributos adicionales.

El comando pasa a process_tiles los identificadores que elige de clouds(), también de nubes ocultas. Cada nube debe estar abierta y aportar los atributos pedidos. Para modificar puntos, cada nube necesita registro de ediciones e índices originales. Con read_only=True, el programa no exige esos dos datos y entrega result=None.

process_tile(tile, result, host) recibe un Tile, un TileResult y un TileHost. La función retorna sin código de estado. Una excepción provoca el fallo del procesamiento; KeyboardInterrupt o la cancelación del anfitrión cancelan la tesela.

concurrent=True permite varias teselas en hilos diferentes, que se turnan para ejecutar Python con el bloqueo global del intérprete (GIL, del inglés Global Interpreter Lock). estimated_peak_bytes_per_point estima la memoria máxima que asigna el cálculo por punto. El valor 0 aplica lop.DEFAULT_PEAK_BYTES_PER_POINT, que vale 1024 bytes por punto.

El programa muestra los resultados durante el procesamiento. Una llamada que confirma cambios en puntos añade un evento al historial. El historial muestra el nombre actual del comando si está disponible, o el código. TilesSummary contiene reclassified_point_count, deleted_point_count y changed_cloud_count. La cancelación descarta los resultados de esa llamada. Un fallo al guardar puede dejar cambios confirmados en algunas nubes.

Durante la llamada, el usuario no puede cerrar las nubes reservadas; puede abrir otras y cerrar nubes no reservadas. Al cerrar Lot Of Points, el programa solicita la cancelación y espera hasta 3 segundos a que terminen los hilos de comandos.

Tile, TileResult y TileHost

Tile contiene las columnas de puntos, sin cloud_id por columna, y añade in_core, gps_time y point_source_id. Los atributos adicionales valen None si las opciones no los piden. Sus propiedades point_count, core_min, core_max, tile_index, tile_count y cloud_id identifican la tesela. len(tile) devuelve point_count.

Cada columna de Tile es una copia de solo lectura que se crea al acceder a la columna por primera vez. Una copia ya leída sigue siendo válida cuando termina la función de la tesela. Leer por primera vez una columna existente de una tesela con puntos después de terminar la función lanza RuntimeError.

TileResult.classification comienza con las clases de la tesela y deleted comienza con ceros. La función puede modificar los arrays o sustituirlos por arrays de la misma longitud. Las clases deben ser enteros de 0 a 255; un valor distinto de 0 en deleted marca el punto para borrar. Cuando la función termina normalmente, el programa valida y copia al resultado nativo las columnas leídas o asignadas. El programa guarda únicamente los resultados de los puntos del núcleo.

TileHost proporciona report_tile_progress(fraction), cancelled(), log(message) y max_worker_thread_count(). report_tile_progress recibe una fracción de progreso entre 0 y 1, ambos incluidos. Después de terminar la función de la tesela, cancelled() devuelve True, los métodos de progreso y registro no realizan acciones y max_worker_thread_count() conserva su valor.