============================================ Loading clouds and other entities from files ============================================ .. _load_formats: Known formats ------------- Entities known by CloudComPy are mainly PointClouds, triangular meshes, polylines... CloudComPy can read a lot of formats of point clouds and meshes. The ``.bin`` binary format is the native format of CloudCompare and can store several entities of all types. Take a look at the details of the formats supported by CloudCompare on `wiki `_. For clouds, the extensions known by CloudComPy are: ``.asc`` ``.bin`` ``.drc`` ``.dxf`` ``.E57`` ``.las`` ``.laz`` ``.pcd`` ``.ply`` ``.pv`` ``.sbf`` ``.shp`` ``.vtk`` ``.xyz`` For meshes: ``.dxf`` ``.bin`` ``.fbx`` ``.obj`` ``.off`` ``.ply`` ``.stl`` ``.vtk`` For polylines: ``.dxf`` ``.poly`` ``.sx`` ``.shp`` See :download:`test020.py <../tests/test020.py>` for an example. Load without explicit shift parameters -------------------------------------- By default, CloudCompare applies an automatic coordinates shift to recenter the objects and avoid a loss of precision. This is transparent for the user, and is the best option unless you need to load several entities while keeping the same shift. In that case, see :ref:`loadParameters-label` below. If you want to know if a coordinate shift has been applied when loading an object, and the value of the shift, see :ref:`shiftValue-label` below. For all the examples below, we can use the files generated by autotests (see `here `_ for Linux or `there `_ for Windows. These files are, by default, in the subdirectory `CloudComPy/Data` of your Home. Let's start by changing the working directory for your HOME. :: os.chdir(os.path.expanduser("~")) Loading a point cloud ~~~~~~~~~~~~~~~~~~~~~ The :py:func:`cloudComPy.loadPointCloud` returns only the first point cloud found in the file. :: cloud = cc.loadPointCloud("CloudComPy/Data/dataSample_1.0.xyz") print(cloud.getName()) Loading a mesh ~~~~~~~~~~~~~~ The :py:func:`cloudComPy.loadMesh` returns only the first mesh found in the file. :: mesh = cc.loadMesh("CloudComPy/Data/mesh.stl") print(mesh.getName()) Loading a polyline ~~~~~~~~~~~~~~~~~~ The :py:func:`cloudComPy.loadPolyline` returns the first polyline found in the file. :: poly = cc.loadPolyline("CloudComPy/Data/poly1.poly") print(poly.getName()) Loading a file containing several entities ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :py:func:`cloudComPy.importFile` returns a tuple (list(mesh), list(cloud), file structure). The lists can be empty, depending on the content of the file. See :ref:`loadStructure-label` below for file structure. For now, CloudComPy detects only meshes and clouds in a ``.bin`` file. For instance, polylines and facets are imported as clouds, primitives are imported as meshes. :: res = cc.importFile("CloudComPy/Data/meshCloud.bin") meshes = res[0] clouds = res[1] for mesh in meshes: print(mesh.getName()) for cloud in clouds: print(cloud.getName()) Select the scans to load in a ``.E57`` file ------------------------------------------- The :py:func:`cloudComPy.importFile` accept an optional parameter, ``extraData`` which a regular expression (see `Qt RegExp `_) used to filter the scans to load in a ``.E57`` file. In the example below, the file contains 5 scans named 'sp2_1', 'sp2_2', 'sp26_1', 'sp25_2', 'sp26_2' The regular expression ``sp2.*_1`` allows to select 'sp2_1' and 'sp26_1' (``.`` means any character, ``*`` means 0 occurence or more of the previous). .. include:: ../tests/test041.py :start-after: #---E57filter-begin :end-before: #---E57filter-end :literal: :code: python With the ``.E57`` file, you always get the structure of the file. You can load the structure first (see :ref:`loadStructure-label` below), with an ``extraData`` pattern excluding all the scans, to get the scan names, then select a pattern to load the scans you want, one or more at a time... .. _loadStructure-label: Loading the file structure ~~~~~~~~~~~~~~~~~~~~~~~~~~ The :py:func:`cloudComPy.importFile` returns the file structure as last item of the return tuple. For instance, ``.E57`` files contains a rich structured set of information. The file structure is given here as an array of strings, the first item of the string is the depth level. For the test, we need a data file `available here `_. .. include:: ../tests/test041.py :start-after: #---sensor001-begin :end-before: #---sensor001-end :literal: :code: python In this example, there are several point clouds in the example, with one sensor per cloud. To get the structure as a list of strings: .. include:: ../tests/test041.py :start-after: #---sensor003-begin :end-before: #---sensor003-end :literal: :code: python The above code snippets are from :download:`test041.py <../tests/test041.py>`. .. _shiftValue-label: Getting the shift value ----------------------- By default, CloudCompare applies an automatic coordinates shift to recenter the objects and avoid a loss of precision. To know if a shift has been applied on an object, use the method :py:meth:`~.cloudComPy.ccShiftedObject.isShifted`. The three components of the shift are given with the method :py:meth:`~.cloudComPy.ccShiftedObject.getGlobalShift`. .. _loadParameters-label: Load with explicit shift parameters ----------------------------------- when you need to load several entities and apply the same shift, the best solution is to use the option ``mode=cc.CC_SHIFT_MODE.XYZ`` followed by the x,y and/or z non null shifts. :: cloud1 = cc.loadPointCloud(filename="CloudComPy/Data/dataSample_5.0.xyz", mode=cc.CC_SHIFT_MODE.XYZ, x=3, z=10) res = cc.importFile(filename="CloudComPy/Data/dataSample_1.0.xyz", mode=cc.CC_SHIFT_MODE.XYZ, x=3, z=10) cloud2 = res[1][0] mesh = cc.loadMesh(filename="CloudComPy/Data/mesh.stl", mode=cc.CC_SHIFT_MODE.XYZ, x=3, z=10) **NOTE** If you don't know the value of the shift to apply, load the first entity without shift parameters, and use the methods :py:meth:`~.cloudComPy.ccShiftedObject.isShifted` and :py:meth:`~.cloudComPy.ccShiftedObject.getGlobalShift` to get a valid shift value. **WARNING** Shift parameters are not always taken into account, depending on the type of file, shift values, following the internal rules of CloudCompare: when using the CloudCompare GUI, shift dialog at import is not always available. When the shift dialog is not proposed in the GUI, shift parameters are likely not taken into account in CloudCompare.