From 1768026891801c2ede9c04abc9e1e12ad2aee1b8 Mon Sep 17 00:00:00 2001 From: Dion Moult Date: Thu, 30 Jan 2025 15:32:14 +1100 Subject: [PATCH] Fix #5854. Update docs with new IOS v0.8 settings. --- src/ifcopenshell-python/docs/ifcconvert.rst | 5 +- .../docs/ifcconvert/usage.rst | 308 +++-- .../geometry_processing.rst | 25 +- src/ifcopenshell-python/docs/ifcopenshell.rst | 1 + .../docs/ifcopenshell/geometry_settings.rst | 1108 ++++++++++------- 5 files changed, 839 insertions(+), 608 deletions(-) diff --git a/src/ifcopenshell-python/docs/ifcconvert.rst b/src/ifcopenshell-python/docs/ifcconvert.rst index bc17accf52..6861eb1120 100644 --- a/src/ifcopenshell-python/docs/ifcconvert.rst +++ b/src/ifcopenshell-python/docs/ifcconvert.rst @@ -2,7 +2,8 @@ IfcConvert ========== IfcConvert is a command-line application for converting IFC geometry into file -formats such as OBJ, DAE, GLB, STP, IGS, XML, SVG, H5, and IFC itself. +formats such as OBJ, DAE, GLB, STP, IGS, XML, SVG, H5, CityJSON, TTL/WKT, and +IFC-SPF itself. For other formats, you may use other IfcOpenShell utilities as shown in the table below. @@ -12,7 +13,7 @@ table below. +=========================+=========================+======================+ | .ifc | .obj, .dae, .glb, .stp, | IfcConvert | | | .igs, .xml, .svg, .h5, | | -| | .ifc | | +| | .cityjson, .ttl, .ifc | | +-------------------------+-------------------------+----------------------+ | .ifc | .dae, .abc, .usd, .obj, | Bonsai_ | | | .ply, .stl, .fbx, .glb, | | diff --git a/src/ifcopenshell-python/docs/ifcconvert/usage.rst b/src/ifcopenshell-python/docs/ifcconvert/usage.rst index 657965a1b6..ffc64f1c08 100644 --- a/src/ifcopenshell-python/docs/ifcconvert/usage.rst +++ b/src/ifcopenshell-python/docs/ifcconvert/usage.rst @@ -70,7 +70,7 @@ CLI Manual $ IfcConvert -h - IfcOpenShell IfcConvert v0.8.0-dc67287d (OCC 7.5.3) + IfcOpenShell IfcConvert 0.8.1-c49ca69 (OCC 7.8.1) Usage: IfcConvert [options] [] Converts (the geometry in) an IFC file into one of the following formats: @@ -82,6 +82,8 @@ CLI Manual .xml XML Property definitions and decomposition tree .svg SVG Scalable Vector Graphics (2D floor plan) .h5 HDF Hierarchical Data Format storing positions, normals and indices + .cityjson City JSON format for geospatial data + .ttl TTL/WKT RDF Turtle with Well-Known-Text geometry .ifc IFC-SPF Industry Foundation Classes If no output filename given, .obj will be used as the output file. @@ -92,9 +94,6 @@ CLI Manual --version display version information -v [ --verbose ] more verbose log messages. Use twice (-vv) for debugging level. - -d [ --debug ] write boolean operands to file in - current directory for debugging - purposes -q [ --quiet ] less status and progress output --cache cache geometry creation. Use --cache-file to specify cache file @@ -109,42 +108,10 @@ CLI Manual --log-file arg redirect log output to file Geometry options: + --kernel arg (=opencascade) Geometry kernel to use (opencascade, + cgal, cgal-simple). -j [ --threads ] arg (=1) Number of parallel processing threads for geometry interpretation. - --plan Specifies whether to include curves in - the output result. Typically these are - representations of type Plan or Axis. - Excluded by default. - --model Specifies whether to include surfaces - and solids in the output result. - Typically these are representations of - type Body or Facetation. Included by - default. - --weld-vertices Specifies whether vertices are welded, - meaning that the coordinates vector - will only contain unique xyz-triplets. - This results in a manifold mesh which - is useful for modelling applications, - but might result in unwanted shading - artefacts in rendering applications. - --use-world-coords Specifies whether to apply the local - placements of building elements - directly to the coordinates of the - representation mesh rather than to - represent the local placement in the - 4x3 matrix, which will in that case be - the identity matrix. - --convert-back-units Specifies whether to convert back - geometrical output back to the unit of - measure in which it is defined in the - IFC file. Default is to use meters. - --orient-shells Specifies whether to orient the faces - of IfcConnectedFaceSets. This is a - potentially time consuming operation, - but guarantees a consistent orientation - of surface normals, even if the faces - are not properly oriented in the IFC - file. --center-model Centers the elements by applying the center point of all placements as an offset.Can take several minutes on @@ -152,26 +119,6 @@ CLI Manual --center-model-geometry Centers the elements by applying the center point of all mesh vertices as an offset. - --model-offset arg Applies an arbitrary offset of form - 'x;y;z' to all placements. - --model-rotation arg Applies an arbitrary quaternion - rotation of form 'x;y;z;w' to all - placements. - --disable-opening-subtractions Specifies whether to disable the - boolean subtraction of - IfcOpeningElement Representations from - their RelatingElements. - --disable-boolean-results Specifies whether to disable the - boolean operation within - representations such as clippings by - means of IfcBooleanResult and subtypes - --no-2d-boolean Do not attempt to process boolean - subtractions in 2D. - --enable-layerset-slicing Specifies whether to enable the slicing - of products according to their - associated IfcMaterialLayerSet. - --layerset-first Assigns the first layer material of the - layerset to the complete product. --include arg Specifies that the instances that match a specific filtering criteria are to be included in the geometrical output: @@ -227,40 +174,159 @@ CLI Manual inserted on their own lines. See --include, --include+, --exclude, and --exclude+ for more details. - --no-normals Disables computation of normals. Saves + --default-material-file arg Specifies a material file that + describes the material object types + will haveif an object does not have any + specified material in the IFC file. + --exterior-only [=arg(=minkowski-triangles)] (=none) + Export only the exterior shell of the + building found by geometric analysis. + convex-decomposition, + minkowski-triangles or + halfspace-snapping + --plan Specifies whether to include curves in + the output result. Typically these are + representations of type Plan or Axis. + Excluded by default. + --model Specifies whether to include surfaces + and solids in the output result. + Typically these are representations of + type Body or Facetation. + --mesher-linear-deflection arg (= 0.001) + Specifies the linear deflection of the + mesher. Controls the detail of curved + surfaces in triangulated output + formats. + --mesher-angular-deflection arg (= 0.5) + Sets the angular tolerance of the + mesher in radians 0.5 by default if not + specified. + --reorient-shells Specifies whether to orient the faces + of IfcConnectedFaceSets. This is a + potentially time consuming operation, + but guarantees a consistent orientation + of surface normals, even if the faces + are not properly oriented in the IFC + file. + --length-unit arg (= 1) + --angle-unit arg (= 1) + --precision arg (= 1e-05) + --dimensionality arg (= 1) Specifies whether to include curves + and/or surfaces and solids in the + output result. Defaults to only + surfaces and solids. + --layerset-first Assigns the first layer material of the + layerset to the complete product. + --disable-boolean-result Specifies whether to disable the + boolean operation within + representations such as clippings by + means of IfcBooleanResult and subtypes + --no-wire-intersection-check Skip wire intersection check. + --no-wire-intersection-tolerance arg (= 0) + Set wire intersection tolerance to 0. + --precision-factor arg (= 1) Option to increase linear tolerance for + more permissive edge curves and fewer + artifacts after boolean operations at + the expense of geometric detail due to + vertex collapsing and wire intersection + fuzziness. + --debug write boolean operands to file in + current directory for debugging + purposes + --boolean-attempt-2d Do not attempt to process boolean + subtractions in 2D. + --surface-colour Prioritizes the surface color instead + of using diffuse. + --weld-vertices Specifies whether vertices are welded, + meaning that the coordinates vector + will only contain unique xyz-triplets. + This results in a manifold mesh which + is useful for modelling applications, + but might result in unwanted shading + artefacts in rendering applications. + --use-world-coords Specifies whether to apply the local + placements of building elements + directly to the coordinates of the + representation mesh rather than to + represent the local placement in the + 4x3 matrix, which will in that case be + the identity matrix. + --unify-shapes Unify adjacent co-planar and co-linear + subshapes (topological entities sharing + the same geometric domain) before + triangulation or further processing + --use-material-names Use material names instead of unique + IDs for naming materials upon + serialization. Applicable for OBJ and + DAE output. + --convert-back-units Specifies whether to convert back + geometrical output back to the unit of + measure in which it is defined in the + IFC file. Default is to use meters. + --context-ids arg + --context-ids arg + --context-ids arg + --iterator-output arg (= 0) + --disable-opening-subtractions Specifies whether to disable the + boolean subtraction of + IfcOpeningElement Representations from + their RelatingElements. + --apply-default-materials + --no-normals Disables computation of normals.Saves time and file size and is useful in instances where you're going to recompute normals for the exported model in other modelling application in any case. - --deflection-tolerance arg (=0.001) Sets the deflection tolerance of the - mesher, 1e-3 by default if not - specified. - --force-space-transparency arg Overrides transparency of spaces in - geometry output. - --angular-tolerance arg (=0.5) Sets the angular tolerance of the - mesher in radians 0.5 by default if not - specified. --generate-uvs Generates UVs (texture coordinates) by using simple box projection. Requires normals. Not guaranteed to work properly if used with --weld-vertices. - --default-material-file arg Specifies a material file that - describes the material object types - will haveif an object does not have any - specified material in the IFC file. + --enable-layerset-slicing Specifies whether to enable the slicing + of products according to their + associated IfcMaterialLayerSet. + --element-hierarchy Assign the elements using their e.g + IfcBuildingStorey parent.Applicable to + DAE output. --validate Checks whether geometrical output conforms to the included explicit quantities. - --no-wire-intersection-check Skip wire intersection check. - --no-wire-intersection-tolerance Set wire intersection tolerance to 0. - --strict-tolerance Use exact tolerance from model. Default - is a 10 times increase for more - permissive edge curves and fewer - artifacts after boolean operations at - the expense of geometric detail due to - vertex collapsing and wire intersection - fuzziness. + --edge-arrows Adds arrow heads to edge segments to + signify edge direction + --building-local-placement Similar to --site-local-placement, but + placing elements in locally in the + parent IfcBuilding coord system + --site-local-placement Place elements locally in the IfcSite + coordinate system, instead of placing + them in the IFC global coords. + Applicable for OBJ, DAE, and STP + output. + --force-space-transparency arg Overrides transparency of spaces in + geometry output. + --circle-segments arg (= 16) Number of segments to approximate full + circles in CGAL kernel. + --keep-bounding-boxes Default is to removes IfcBoundingBox + from model prior to converting + geometry.Setting this option disables + that behaviour + --function-step-type arg (= 0) Indicates the method used for defining + step size when evaluating + function-based curves. Provides + interpretation of function-step-param + --function-step-param arg (= 0.5) Indicates the parameter value for + defining step size when evaluating + function-based curves. + --no-parallel-mapping Perform mapping upfront + (single-threaded) as opposed to in + parallel. May decrease performance, but + also decrease output size (in the + future) + --model-offset arg Applies an arbitrary offset of form + 'x,y,z' to all placements. + --model-rotation arg Applies an arbitrary quaternion + rotation of form 'x,y,z,w' to all + placements. + --triangulation-type arg (= 0) Type of planar facet to be emitted Serialization options: --bounds arg Specifies the bounding rectangle, for @@ -296,6 +362,10 @@ CLI Manual data-guid --svg-poly Uses the polygonal algorithm for hidden line rendering + --svg-prefilter Prefilter faces and shapes before + feeding to HLR algorithm + --svg-segment-projection Segment result of projection wrt + original products --svg-write-poly Approximate every curve as polygonal in SVG output --svg-project Always enable hidden line rendering @@ -310,47 +380,6 @@ CLI Manual --section-height-from-storeys Derives section height from storey elevation. Use --section-height to override default offset of 1.2 - --use-element-names Use entity instance IfcRoot.Name - instead of unique IDs for naming - elements upon serialization. Applicable - for OBJ, DAE, and SVG output. - --use-element-guids Use entity instance IfcRoot.GlobalId - instead of unique IDs for naming - elements upon serialization. Applicable - for OBJ, DAE, and SVG output. - --use-element-numeric-ids Use the numeric step identifier (entity - instance name) for naming elements upon - serialization. Applicable for OBJ, DAE, - and SVG output. - --use-material-names Use material names instead of unique - IDs for naming materials upon - serialization. Applicable for OBJ and - DAE output. - --use-element-types Use element types instead of unique IDs - for naming elements upon serialization. - Applicable for DAE output. - --use-element-hierarchy Order the elements using their - IfcBuildingStorey parent. Applicable - for DAE output. - --site-local-placement Place elements locally in the IfcSite - coordinate system, instead of placing - them in the IFC global coords. - Applicable for OBJ and DAE output. - --y-up Change the 'up' axis to positive Y, - default is Z UP, Applicable for OBJ - output. - --building-local-placement Similar to --site-local-placement, but - placing elements in locally in the - parent IfcBuilding coord system - --precision arg (=15) Sets the precision to be used to format - floating-point values, 15 by default. - Use a negative value to use the - system's default precision (should be 6 - typically). Applicable for OBJ and DAE - output. For DAE output, value >= 15 - means that up to 16 decimals are used, - and any other value means that 6 or 7 - decimals are used. --print-space-names Prints IfcSpace LongName and Name in the geometry output. Applicable for SVG output @@ -359,6 +388,37 @@ CLI Manual output --space-name-transform arg Additional transform to the space labels in SVG - --edge-arrows Adds arrow heads to edge segments to - signify edge direction - + --use-element-names Use entity instance IfcRoot.Name + instead of unique IDs for naming + elements upon serialization. Applicable + for OBJ, DAE, STP, and SVG output. + --use-element-guids Use entity instance IfcRoot.GlobalId + instead of unique IDs for naming + elements upon serialization. Applicable + for OBJ, DAE, STP, and SVG output. + --use-element-step-ids Use the numeric step identifier (entity + instance name) for naming elements upon + serialization. Applicable for OBJ, DAE, + STP, and SVG output. + --use-element-types Use element types instead of unique IDs + for naming elements upon serialization. + Applicable to DAE output. + --y-up Change the 'up' axis to positive Y, + default is Z UP. Applicable to OBJ + output. + --ecef Write glTF in Earth-Centered + Earth-Fixed coordinates. Requires PROJ. + --digits arg (= 15) Sets the precision to be used to format + floating-point values, 15 by default. + Use a negative value to use the + system's default precision (should be 6 + typically). Applicable for OBJ and DAE + output. For DAE output, value >= 15 + means that up to 16 decimals are used, + and any other value means that 6 or 7 + decimals are used. + --base-uri arg Base URI for products to be used in + RDF-based serializations. + --wkt-use-section Use a geometrical section rather than + full polyhedral output and footprint in + TTL WKT diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python/geometry_processing.rst b/src/ifcopenshell-python/docs/ifcopenshell-python/geometry_processing.rst index 8fef2150a4..df7ae3321e 100644 --- a/src/ifcopenshell-python/docs/ifcopenshell-python/geometry_processing.rst +++ b/src/ifcopenshell-python/docs/ifcopenshell-python/geometry_processing.rst @@ -128,7 +128,7 @@ Alternatively, you may choose to retrieve an OpenCASCADE BRep: element = ifc_file.by_type('IfcWall')[0] settings = ifcopenshell.geom.settings() - settings.set(settings.USE_PYTHON_OPENCASCADE, True) + settings.set("use-python-opencascade", True) try: shape = geom.create_shape(settings, element) @@ -301,6 +301,9 @@ Here is a typical example to serialising to glTF / glb. Example settings to serialise to other formats are shown commented out. Different serialisations may require different settings. +In addition to geometry settings, serialisation has its own set of +:doc:`../ifcopenshell/serialiser_settings`. + .. code-block:: python import ifcopenshell @@ -310,25 +313,23 @@ may require different settings. settings = ifcopenshell.geom.settings() # Settings for glTF / glb - settings.set(settings.STRICT_TOLERANCE, True) - settings.set(settings.INCLUDE_CURVES, True) - # Setting element GUIDs is optional, but useful to uniquely identify objects in non-semantic formats. - settings.set(settings.USE_ELEMENT_GUIDS, True) + settings.set("dimensionality", ifcopenshell.ifcopenshell_wrapper.CURVES_SURFACES_AND_SOLIDS) # Note that applying default materials is required in glTF serialisation. - settings.set(settings.APPLY_DEFAULT_MATERIALS, True) + settings.set("apply-default-materials", True) # Settings for obj - # settings.set(settings.STRICT_TOLERANCE, True) - # settings.set(settings.INCLUDE_CURVES, True) - # settings.set(settings.USE_ELEMENT_GUIDS, True) - # settings.set(settings.APPLY_DEFAULT_MATERIALS, True) - # settings.set(settings.USE_WORLD_COORDS, True) + # settings.set("dimensionality", ifcopenshell.ifcopenshell_wrapper.CURVES_SURFACES_AND_SOLIDS) + # settings.set("apply-default-materials", True) + # settings.set("use-world-coords", True) # Serialise to glTF / glb serialiser = ifcopenshell.geom.serializers.gltf("output.glb", settings) + self.serialiser_settings = ifcopenshell.geom.serializer_settings() + # Setting element GUIDs is optional, but useful to uniquely identify objects in non-semantic formats. + serialiser_settings.set("use-element-guids", True) # Serialise to obj - # serialiser = ifcopenshell.geom.serializers.obj('output.obj', 'output.mtl', settings) + # serialiser = ifcopenshell.geom.serializers.obj('output.obj', 'output.mtl', settings, serialiser_settings) serialiser.setFile(self.file) serialiser.setUnitNameAndMagnitude("METER", 1.0) diff --git a/src/ifcopenshell-python/docs/ifcopenshell.rst b/src/ifcopenshell-python/docs/ifcopenshell.rst index d85eb74da7..92d533d4ae 100644 --- a/src/ifcopenshell-python/docs/ifcopenshell.rst +++ b/src/ifcopenshell-python/docs/ifcopenshell.rst @@ -24,4 +24,5 @@ possible at compile-time when using C++ and at run-time when using Python. ifcopenshell/getting_started ifcopenshell/geometry_iterator ifcopenshell/geometry_settings + ifcopenshell/serialiser_settings ifcopenshell/boolean_process diff --git a/src/ifcopenshell-python/docs/ifcopenshell/geometry_settings.rst b/src/ifcopenshell-python/docs/ifcopenshell/geometry_settings.rst index 1299fe2e27..a41489a4dd 100644 --- a/src/ifcopenshell-python/docs/ifcopenshell/geometry_settings.rst +++ b/src/ifcopenshell-python/docs/ifcopenshell/geometry_settings.rst @@ -2,12 +2,6 @@ Geometry settings ================= The geometry iterator has a variety of settings which can impact its output. -Some of these are set during the construction of the iterator, whereas some are -set in a specific iterator settings object. - -All UPPERCASE settings are booleans which are always set in a separate settings -object. Lowercase settings are set either during iterator construction or via a -setting function. All settings can be accessed with C++ and Python, but only some are exposed in IfcConvert via command line arguments. @@ -18,7 +12,6 @@ Here's an example of changing settings in C++: SerializerSettings settings; settings.set(IfcGeom::IteratorSettings::APPLY_DEFAULT_MATERIALS, true); - settings.set_deflection_tolerance(1e-3); Here's an example of changing settings in Python: @@ -26,327 +19,15 @@ Here's an example of changing settings in Python: settings = ifcopenshell.geom.settings() settings.set("apply-default-materials", True) - settings.set_deflection_tolerance(1e-3) -angular_tolerance ------------------ -+--------+-------------------------+---------+ -| Type | IfcConvert Option | Default | -+========+=========================+=========+ -| DOUBLE | ``--angular-tolerance`` | 0.5 | -+--------+-------------------------+---------+ +Iterator instance settings +-------------------------- -Sets the angular tolerance of the mesher in radians. - -Here is an example in C++: - -.. code-block:: c++ - - SerializerSettings settings; - double tolerance; - // ... - settings.set_angular_tolerance(tolerance); - -Here is an example in Python: - -.. code-block:: python - - settings = ifcopenshell.geom.settings() - settings.set("mesher-angular-deflection", 0.5) - -APPLY_DEFAULT_MATERIALS ------------------------ - -+------+-------------------+---------+ -| Type | IfcConvert Option | Default | -+======+===================+=========+ -| BOOL | Always enabled | True | -+------+-------------------+---------+ - -Given the command invocation: - -:: - - IfcConvert model.ifc d.dae -yv --include attribute GlobalId 3bXiCStxP6Fgxdej$yc50U - -You will find log messages along the lines of - - [Warning] {3bXiCStxP6Fgxdej$yc50U} No material and surface styles for: - #333=IfcCovering('3bXiCStxP6Fgxdej$yc50U',#1,'Compound Ceiling:Gypsum Board:187483',$,'Compound Ceiling:Gypsum Board',#17840,#17052,'187483',.CEILING.) - -This means that there is no IfcStyledItem associated to the representation items and that the element does not have an IfcMaterial association with IfcMaterialRepresentation from which we can derive a style (colour) for the element. - -The interactive session below shows how with this setting enabled you will get a default generated material from the IFC element entity type and material indices of 0 pointing to that. With this setting disabled the material index would be -1 to indicate a missing style. Note that there is one material index for every triangle in the list of `shp.geometry.faces`. - - >>> import ifcopenshell, ifcopenshell.geom - >>> f = ifcopenshell.open("model.ifc") - >>> s = ifcopenshell.geom.settings() - >>> # By default setting is enabled, we disable it for demonstration. - >>> s.set("apply-default-materials", False) - >>> c = f["3bXiCStxP6Fgxdej$yc50U"] - >>> - >>> shp = ifcopenshell.geom.create_shape(s, c) - >>> shp.geometry.material_ids - (-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1) - >>> [(m.name, m.diffuse) for m in shp.geometry.materials] - [] - >>> - >>> s.set("apply-default-materials", True) - >>> shp = ifcopenshell.geom.create_shape(s, c) - >>> shp.geometry.material_ids - (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0) - >>> [(m.name, m.diffuse) for m in shp.geometry.materials] - [('IfcCovering', colour 0.7 0.7 0.7)] - -This is enabled by default for the IfcConvert serializers as they will not gracefully handle -1 material indices and allows users to quickly assign colours based on entity types in their modelling applications. - -APPLY_LAYERSETS ---------------- - -+------+-------------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+===============================+=========+ -| BOOL | ``--enable-layerset-slicing`` | False | -+------+-------------------------------+---------+ - -For IfcWall and IfcSlab elements, takes the associated IfcMaterialLayerSet and builds a set of surfaces to segment the building element geometry. - -.. warning:: - - Enabling this settings is computationally intensive as it involves 3D Boolean operations. - -:: - - IfcConvert model.ifc d1.dae -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 - -.. image:: images/settings-1.png - -:: - - IfcConvert model.ifc d2.dae --enable-layerset-slicing -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 - -.. image:: images/settings-2.png - -BOOLEAN_ATTEMPT_2D ------------------- - -+------+---------------------+---------+ -| Type | IfcConvert Option | Default | -+======+=====================+=========+ -| BOOL | ``--no-2d-boolean`` | True | -+------+---------------------+---------+ - -Try to perform boolean subtractions in 2d. This can result in 2-3x faster geometry processing. - -BUILDING_LOCAL_PLACEMENT ------------------------- - -+------+--------------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+================================+=========+ -| BOOL | ``--building-local-placement`` | False | -+------+--------------------------------+---------+ - -In the typical IfcSite > IfcBuilding > IfcBuildingStorey > ... hierarchy of elements, don't incorporate the ObjectPlacement of the IfcBuilding and above in the placement of elements in the output. This is useful when there is a large offset in this placement that reduces precision in further processing. - -context_ids ------------ - -+-------------+-------------------+---------+ -| Type | IfcConvert Option | Default | -+=============+===================+=========+ -| LIST OF INT | N/A | NULL | -+-------------+-------------------+---------+ - -By default, geometry is processed from all geometric representation contexts. -In C++ and Python, it is possible to specify exactly which contexts should be -processed, by passing in a list of integers, where the integers are the IDs of -the contexts. Typically used to target only Body representations or non-Body -representations. - -Here is an example in C++: - -.. code-block:: c++ - - SerializerSettings settings; - std::vector context_ids; - // ... - settings.set_context_ids(context_ids); - -Here is an example in Python: - -.. code-block:: python - - settings = ifcopenshell.geom.settings() - contexts = [c.id() for c in ifc_file.by_type("IfcGeometricRepresentationContext") if c.ContextIdentifier == "Body"] - settings.set("context-ids", contexts) - - -CONVERT_BACK_UNITS ------------------- - -+------+--------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+==========================+=========+ -| BOOL | ``--convert-back-units`` | False | -+------+--------------------------+---------+ - -Internally IfcOpenShell uses meters as the global length unit to do calculations. This setting restores the coordinate positions after conversion by multiplying the factor of the IfcUnit with UnitType=LENGTHUNIT into the output geometry coordinate values. - -DEBUG_BOOLEAN -------------- - -+------+-----------------------+---------+ -| Type | IfcConvert Option | Default | -+======+=======================+=========+ -| BOOL | ``--debug`` or ``-d`` | False | -+------+-----------------------+---------+ - -Write boolean operands to file in current directory for debugging purposes. - -deflection_tolerance --------------------- - -+--------+----------------------------+---------+ -| Type | IfcConvert Option | Default | -+========+============================+=========+ -| DOUBLE | ``--deflection-tolerance`` | 1e-3 | -+--------+----------------------------+---------+ - -Sets the deflection tolerance of the mesher. - -Here is an example in C++: - -.. code-block:: c++ - - SerializerSettings settings; - double tolerance; - // ... - settings.set_deflection_tolerance(tolerance); - -Here is an example in Python: - -.. code-block:: python - - settings = ifcopenshell.geom.settings() - settings.set("mesher-linear-deflection", 1e-3) - -DISABLE_BOOLEAN_RESULT ----------------------- - -+------+-------------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+===============================+=========+ -| BOOL | ``--disable-boolean-results`` | False | -+------+-------------------------------+---------+ - -Disables the evaluation of IfcBooleanResult and simply returns FirstOperand. - -DISABLE_OPENING_SUBTRACTIONS ----------------------------- - -+------+------------------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+====================================+=========+ -| BOOL | ``--disable-opening-subtractions`` | False | -+------+------------------------------------+---------+ - -As in most viewer applications, IfcOpeningElement geometry is subtracted from their host elements. This setting disables this behavior. - -:: - - IfcConvert model.ifc d1.dae -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 - -.. image:: images/settings-1.png - -:: - - IfcConvert model.ifc d3.dae --disable-opening-subtraction -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 - -.. image:: images/settings-3.png - -.. note:: - - Disabling this settings will reduce processing time and improve robustness as it involves 3D Boolean operations. - -For example, if you want to set this setting in a python script you can use the following: - -.. code-block:: python - - settings = ifcopenshell.geom.settings() - settings.set("disable-opening-subtractions", True) - - -DISABLE_TRIANGULATION ---------------------- - -+------+------------------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+====================================+=========+ -| BOOL | True for SVG, HDF, otherwise False | False | -+------+------------------------------------+---------+ - -By default, the iterator returns triangulated geometry. This setting allows to -disable triangulation, and instead to output BReps. Therefore, it is to be used -in conjunction with ``USE_BREP_DATA``. When ``DISABLE_TRIANGULATION`` is set to -False and ``USE_BREP_DATA`` is set to True, the iterator will return a -OpenCASCADE serialized TopoDS_Shape from ``create_shape()`` and ``iterator``. - - >>> import ifcopenshell, ifcopenshell.geom - >>> s = ifcopenshell.geom.settings() - >>> s.set(s.DISABLE_TRIANGULATION, True) - >>> s.set(s.USE_BREP_DATA, True) - >>> f = ifcopenshell.open("model.ifc") - >>> c = f["3bXiCStxP6Fgxdej$yc50U"] - >>> shp = ifcopenshell.geom.create_shape(s, c) - >>> print(shp.geometry.brep_data) - - CASCADE Topology V1, (c) Matra-Datavision - Locations 0 - Curve2ds 0 - Curves 12 - 1 4.6750000000000034 -8.0749999999999904 2.657 -2.0455514041918775e-15 -1 0 - 1 4.6750000000000034 -8.0749999999999904 2.657 1 -3.435893306383461e-15 0 - 1 6.2260000000000044 -8.0749999999999957 2.657 -2.0455514041918724e-15 -1 0 - 1 6.226 -10.246000000000031 2.657 -1 6.8717866127669219e-15 0 - ... - -EDGE_ARROWS ------------ - -+------+-------------------+---------+ -| Type | IfcConvert Option | Default | -+======+===================+=========+ -| BOOL | ``--edge-arrows`` | False | -+------+-------------------+---------+ - -When ``INCLUDE_CURVES`` is true and geometric elements include curves (such as the wall axis), add arrow heads to the edges to indicate direction of the curve. - -:: - - IfcConvert model.ifc d4.dae --model --plan --edge-arrows -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 - -.. image:: images/settings-4.png - - -ELEMENT_HIERARCHY ------------------ - -+------+-----------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+=============================+=========+ -| BOOL | ``--use-element-hierarchy`` | False | -+------+-----------------------------+---------+ - -.. warning:: - - Only applicable to Collada .DAE output when used from IfcConvert. - -Emit the relative placements from IFC instead of a flat listing of absolute placements. +These settings are specific to an individual instance of an iterator object. exclude -------- +^^^^^^^ +-------------+----------------------------------+---------+ | Type | IfcConvert Option | Default | @@ -360,51 +41,8 @@ exclude options are mutually exclusive. See include for more details. -EXCLUDE_SOLIDS_AND_SURFACES ---------------------------- - -+------+------------------------------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+================================================+=========+ -| BOOL | ``--plan`` is used and ``--model`` is not used | False | -+------+------------------------------------------------+---------+ - -Exclude faces, shells and solids from geometrical output. - -FASTER_BOOLEANS ---------------- - -+------+-------------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+===============================+=========+ -| BOOL | ``--merge-boolean-operands`` | False | -+------+-------------------------------+---------+ - -.. warning:: - - Only applicable when using OCCT 6.9 and earlier. - -Fuse the collection of all boolean operands into a single union before applying the boolean subtraction, as opposed to doing individual subtractions. This likely improves performance. From OCCT 7.0 onwards the boolean operations with multiple arguments is used. - -GENERATE_UVS ------------- - -+------+--------------------+---------+ -| Type | IfcConvert Option | Default | -+======+====================+=========+ -| BOOL | ``--generate-uvs`` | False | -+------+--------------------+---------+ - -Applies a box projection on the generated geometry for the element to obtain UV coordinates. This is purely generated, it does not involve texture coordinates stored in the IFC model. - -:: - - IfcConvert model.ifc d5.dae --generate-uvs -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 - -.. image:: images/settings-5.png - include -------- +^^^^^^^ +-------------+----------------------------------+---------+ | Type | IfcConvert Option | Default | @@ -449,67 +87,8 @@ IFC entity instances: iterator = ifcopenshell.geom.iterator(settings, ifc_file, include=ifc_file.by_type("IfcWall"), exclude=None) -INCLUDE_CURVES --------------- - -+------+--------------------+---------+ -| Type | IfcConvert Option | Default | -+======+====================+=========+ -| BOOL | ``--plan`` | False | -+------+--------------------+---------+ - -Include edge and wire geometries in the geometric output. - -LAYERSET_FIRST --------------- - -+------+----------------------+---------+ -| Type | IfcConvert Option | Default | -+======+======================+=========+ -| BOOL | ``--layerset-first`` | False | -+------+----------------------+---------+ - -When not using APPLY_LAYERSETS, take the first material layer from the set to use as the material for the overall element. - -NO_NORMALS ----------- - -+------+-------------------+---------+ -| Type | IfcConvert Option | Default | -+======+===================+=========+ -| BOOL | ``--no-normals`` | False | -+------+-------------------+---------+ - -Do not emit normals on geometric output - -NO_WIRE_INTERSECTION_CHECK --------------------------- - -+------+----------------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+==================================+=========+ -| BOOL | ``--no-wire-intersection-check`` | False | -+------+----------------------------------+---------+ - -Disables wire intersection checks. These checks are done on faces to prevent -self-intersections of face bounds. Self-intersections reduce the reliability of -boolean operations and may lead to crashes. - -NO_WIRE_INTERSECTION_TOLERANCE ------------------------------- - -+------+--------------------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+======================================+=========+ -| BOOL | ``--no-wire-intersection-tolerance`` | False | -+------+--------------------------------------+---------+ - -Set wire intersection tolerance to 0. By default the above check is done using a -tolerance criterium. So that when a vertex is a certain epsilon distance away -from an edge this is flagged as an intersection. - num_threads ------------ +^^^^^^^^^^^ +------+-------------------------+---------+ | Type | IfcConvert Option | Default | @@ -532,8 +111,492 @@ In Python, this is set when the iterator is constructed: import multiprocessing iterator = ifcopenshell.geom.iterator(settings, ifc_file, num_threads=multiprocessing.cpu_count()) -offset ------- +Iterator settings +----------------- + +These settings are set within the iterator settings object and can be shared between iterator instances. + +angle_unit +^^^^^^^^^^ + ++--------+-------------------+---------+ +| Type | IfcConvert Option | Default | ++========+===================+=========+ +| DOUBLE | ``--angle-unit`` | 1 | ++--------+-------------------+---------+ + +Override the plane angle unit being defined in the IFC. + +apply-default-materials +^^^^^^^^^^^^^^^^^^^^^^^ + ++------+-------------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+===============================+=========+ +| BOOL | ``--apply-default-materials`` | True | ++------+-------------------------------+---------+ + +Given the command invocation: + +:: + + IfcConvert model.ifc d.dae -yv --include attribute GlobalId 3bXiCStxP6Fgxdej$yc50U + +You will find log messages along the lines of + + [Warning] {3bXiCStxP6Fgxdej$yc50U} No material and surface styles for: + #333=IfcCovering('3bXiCStxP6Fgxdej$yc50U',#1,'Compound Ceiling:Gypsum Board:187483',$,'Compound Ceiling:Gypsum Board',#17840,#17052,'187483',.CEILING.) + +This means that there is no IfcStyledItem associated to the representation items and that the element does not have an IfcMaterial association with IfcMaterialRepresentation from which we can derive a style (colour) for the element. + +The interactive session below shows how with this setting enabled you will get a default generated material from the IFC element entity type and material indices of 0 pointing to that. With this setting disabled the material index would be -1 to indicate a missing style. Note that there is one material index for every triangle in the list of `shp.geometry.faces`. + + >>> import ifcopenshell, ifcopenshell.geom + >>> f = ifcopenshell.open("model.ifc") + >>> s = ifcopenshell.geom.settings() + >>> # By default setting is enabled, we disable it for demonstration. + >>> s.set("apply-default-materials", False) + >>> c = f["3bXiCStxP6Fgxdej$yc50U"] + >>> + >>> shp = ifcopenshell.geom.create_shape(s, c) + >>> shp.geometry.material_ids + (-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1) + >>> [(m.name, m.diffuse) for m in shp.geometry.materials] + [] + >>> + >>> s.set("apply-default-materials", True) + >>> shp = ifcopenshell.geom.create_shape(s, c) + >>> shp.geometry.material_ids + (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0) + >>> [(m.name, m.diffuse) for m in shp.geometry.materials] + [('IfcCovering', colour 0.7 0.7 0.7)] + +This is enabled by default for the IfcConvert serializers as they will not gracefully handle -1 material indices and allows users to quickly assign colours based on entity types in their modelling applications. + +boolean-attempt-2d +^^^^^^^^^^^^^^^^^^ + ++------+--------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+==========================+=========+ +| BOOL | ``--boolean-attempt-2d`` | True | ++------+--------------------------+---------+ + +Try to perform boolean subtractions in 2d. This can result in 2-3x faster geometry processing. + +building-local-placement +^^^^^^^^^^^^^^^^^^^^^^^^ + ++------+--------------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+================================+=========+ +| BOOL | ``--building-local-placement`` | False | ++------+--------------------------------+---------+ + +In the typical IfcSite > IfcBuilding > IfcBuildingStorey > ... hierarchy of elements, don't incorporate the ObjectPlacement of the IfcBuilding and above in the placement of elements in the output. This is useful when there is a large offset in this placement that reduces precision in further processing. + + +circle-segments +^^^^^^^^^^^^^^^ + ++------+-----------------------+---------+ +| Type | IfcConvert Option | Default | ++======+=======================+=========+ +| INT | ``--circle-segments`` | 16 | ++------+-----------------------+---------+ + +Number of segments to approximate full circles in CGAL kernel. + +context-identifiers +^^^^^^^^^^^^^^^^^^^ + ++----------------+-------------------+---------+ +| Type | IfcConvert Option | Default | ++================+===================+=========+ +| LIST OF STRING | N/A | NULL | ++----------------+-------------------+---------+ + +By default, geometry is processed from all geometric representation contexts. +In C++ and Python, it is possible to specify exactly which contexts should be +processed, by passing in a list of strings, where the strings are the +``ContextIdentifier`` attribute of the contexts. Typically used to target only +Body representations or non-Body representations. + +.. code-block:: python + + settings = ifcopenshell.geom.settings() + settings.set("context-identifiers", ["Body", "Axis"]) + +context-ids +^^^^^^^^^^^ + ++-------------+-------------------+---------+ +| Type | IfcConvert Option | Default | ++=============+===================+=========+ +| LIST OF INT | N/A | NULL | ++-------------+-------------------+---------+ + +By default, geometry is processed from all geometric representation contexts. +In C++ and Python, it is possible to specify exactly which contexts should be +processed, by passing in a list of integers, where the integers are the IDs of +the contexts. Typically used to target only Body representations or non-Body +representations. + +Here is an example in C++: + +.. code-block:: c++ + + SerializerSettings settings; + std::vector context_ids; + // ... + settings.set_context_ids(context_ids); + +Here is an example in Python: + +.. code-block:: python + + settings = ifcopenshell.geom.settings() + contexts = [c.id() for c in ifc_file.by_type("IfcGeometricRepresentationContext") if c.ContextIdentifier == "Body"] + settings.set("context-ids", contexts) + +context-types +^^^^^^^^^^^^^ + ++----------------+-------------------+---------+ +| Type | IfcConvert Option | Default | ++================+===================+=========+ +| LIST OF STRING | N/A | NULL | ++----------------+-------------------+---------+ + +By default, geometry is processed from all geometric representation contexts. +In C++ and Python, it is possible to specify exactly which contexts should be +processed, by passing in a list of strings, where the strings are the +``ContextType`` attribute of the contexts. Typically used to target only Body +representations or non-Body representations. + +.. code-block:: python + + settings = ifcopenshell.geom.settings() + settings.set("context-types", ["Plan"]) + +convert-back-units +^^^^^^^^^^^^^^^^^^ + ++------+--------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+==========================+=========+ +| BOOL | ``--convert-back-units`` | False | ++------+--------------------------+---------+ + +Internally IfcOpenShell uses meters as the global length unit to do calculations. This setting restores the coordinate positions after conversion by multiplying the factor of the IfcUnit with UnitType=LENGTHUNIT into the output geometry coordinate values. + +debug +^^^^^ + ++------+-------------------+---------+ +| Type | IfcConvert Option | Default | ++======+===================+=========+ +| BOOL | ``--debug`` | False | ++------+-------------------+---------+ + +Write boolean operands to file in current directory for debugging purposes. + +dimensionality +^^^^^^^^^^^^^^ + ++------+----------------------+---------+ +| Type | IfcConvert Option | Default | ++======+======================+=========+ +| BOOL | ``--dimensionality`` | 1 | ++------+----------------------+---------+ + +By default, IfcOpenShell only processes surface and solid geometry. You can +change this to include edge and wire geometries in the geometric output. + +.. code-block:: python + + settings = ifcopenshell.geom.settings() + settings.set("dimensionality", ifcopenshell.ifcopenshell_wrapper.CURVES) # 0 + settings.set("dimensionality", ifcopenshell.ifcopenshell_wrapper.SURFACES_AND_SOLIDS) # 1, default + settings.set("dimensionality", ifcopenshell.ifcopenshell_wrapper.CURVES_SURFACES_AND_SOLIDS) # 2 + +disable-boolean-result +^^^^^^^^^^^^^^^^^^^^^^ + ++------+------------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+==============================+=========+ +| BOOL | ``--disable-boolean-result`` | False | ++------+------------------------------+---------+ + +Disables the evaluation of IfcBooleanResult and simply returns FirstOperand. + + +disable-opening-subtractions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++------+------------------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+====================================+=========+ +| BOOL | ``--disable-opening-subtractions`` | False | ++------+------------------------------------+---------+ + +As in most viewer applications, IfcOpeningElement geometry is subtracted from their host elements. This setting disables this behavior. + +:: + + IfcConvert model.ifc d1.dae -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 + +.. image:: images/settings-1.png + +:: + + IfcConvert model.ifc d3.dae --disable-opening-subtractions -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 + +.. image:: images/settings-3.png + +.. note:: + + Disabling this settings will reduce processing time and improve robustness as it involves 3D Boolean operations. + +For example, if you want to set this setting in a python script you can use the following: + +.. code-block:: python + + settings = ifcopenshell.geom.settings() + settings.set("disable-opening-subtractions", True) + +edge-arrows +^^^^^^^^^^^ + ++------+-------------------+---------+ +| Type | IfcConvert Option | Default | ++======+===================+=========+ +| BOOL | ``--edge-arrows`` | False | ++------+-------------------+---------+ + +When ``INCLUDE_CURVES`` is true and geometric elements include curves (such as the wall axis), add arrow heads to the edges to indicate direction of the curve. + +:: + + IfcConvert model.ifc d4.dae --model --plan --edge-arrows -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 + +.. image:: images/settings-4.png + +element-hierarchy +^^^^^^^^^^^^^^^^^ + ++------+-------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+=========================+=========+ +| BOOL | ``--element-hierarchy`` | False | ++------+-------------------------+---------+ + +.. warning:: + + Only applicable to Collada .DAE output when used from IfcConvert. + +Emit the relative placements from IFC instead of a flat listing of absolute placements. + +enable-layerset-slicing +^^^^^^^^^^^^^^^^^^^^^^^ + ++------+-------------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+===============================+=========+ +| BOOL | ``--enable-layerset-slicing`` | False | ++------+-------------------------------+---------+ + +For IfcWall and IfcSlab elements, takes the associated IfcMaterialLayerSet and builds a set of surfaces to segment the building element geometry. + +.. warning:: + + Enabling this settings is computationally intensive as it involves 3D Boolean operations. + +:: + + IfcConvert model.ifc d1.dae -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 + +.. image:: images/settings-1.png + +:: + + IfcConvert model.ifc d2.dae --enable-layerset-slicing -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 + +.. image:: images/settings-2.png + +force-space-transparency +^^^^^^^^^^^^^^^^^^^^^^^^ + ++--------+--------------------------------+---------+ +| Type | IfcConvert Option | Default | ++========+================================+=========+ +| DOUBLE | ``--force-space-transparency`` | 0 | ++--------+--------------------------------+---------+ + +Overrides transparency of spaces in geometry output. + +function-step-param +^^^^^^^^^^^^^^^^^^^ + ++--------+---------------------------+---------+ +| Type | IfcConvert Option | Default | ++========+===========================+=========+ +| DOUBLE | ``--function-step-param`` | 0.5 | ++--------+---------------------------+---------+ + +Indicates the parameter value for defining step size when evaluating function-based curves. + +function-step-type +^^^^^^^^^^^^^^^^^^ + ++------+--------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+==========================+=========+ +| INT | ``--function-step-type`` | 0 | ++------+--------------------------+---------+ + +Indicates the method used for defining step size when evaluating function-based curves. Provides interpretation of function-step-param + +.. code-block:: python + + settings = ifcopenshell.geom.settings() + settings.set("triangulation-type", ifcopenshell.ifcopenshell_wrapper.MAXSTEPSIZE) # 0 + settings.set("triangulation-type", ifcopenshell.ifcopenshell_wrapper.MINSTEPS) # 1 + +generate-uvs +^^^^^^^^^^^^ + ++------+--------------------+---------+ +| Type | IfcConvert Option | Default | ++======+====================+=========+ +| BOOL | ``--generate-uvs`` | False | ++------+--------------------+---------+ + +Applies a box projection on the generated geometry for the element to obtain UV coordinates. This is purely generated, it does not involve texture coordinates stored in the IFC model. + +:: + + IfcConvert model.ifc d5.dae --generate-uvs -yv --include attribute GlobalId 2O2Fr$t4X7Zf8NOew3FNr2 + +.. image:: images/settings-5.png + +iterator-output +^^^^^^^^^^^^^^^ + +By default, the iterator returns triangulated geometry. This setting allows to +disable triangulation, and instead to output OpenCASCADE serialised +TopoDS_Shape objects. + +.. code-block:: python + + settings = ifcopenshell.geom.settings() + # A string representation of the OCC representation + settings.set("iterator-output", ifcopenshell.ifcopenshell_wrapper.NATIVE) + # A string representation of the OCC representation + settings.set("iterator-output", ifcopenshell.ifcopenshell_wrapper.SERIALIZED) + shape = ifcopenshell.geom.create_shape(settings, element) + print(shape.geometry.brep_data) + + # CASCADE Topology V1, (c) Matra-Datavision + # Locations 0 + # Curve2ds 0 + # Curves 12 + # 1 4.6750000000000034 -8.0749999999999904 2.657 -2.0455514041918775e-15 -1 0 + # 1 4.6750000000000034 -8.0749999999999904 2.657 1 -3.435893306383461e-15 0 + # 1 6.2260000000000044 -8.0749999999999957 2.657 -2.0455514041918724e-15 -1 0 + # 1 6.226 -10.246000000000031 2.657 -1 6.8717866127669219e-15 0 + # ... + +keep-bounding-boxes +^^^^^^^^^^^^^^^^^^^ + ++------+---------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+===========================+=========+ +| BOOL | ``--keep-bounding-boxes`` | False | ++------+---------------------------+---------+ + +Default is to removes IfcBoundingBox from model prior to converting geometry. Setting this option disables that behaviour. + +layerset-first +^^^^^^^^^^^^^^ + ++------+----------------------+---------+ +| Type | IfcConvert Option | Default | ++======+======================+=========+ +| BOOL | ``--layerset-first`` | False | ++------+----------------------+---------+ + +When not using APPLY_LAYERSETS, take the first material layer from the set to use as the material for the overall element. + +length-unit +^^^^^^^^^^^ + ++--------+-------------------+---------+ +| Type | IfcConvert Option | Default | ++========+===================+=========+ +| DOUBLE | ``--length-unit`` | 1 | ++--------+-------------------+---------+ + +Override the length unit being defined in the IFC as a factor of meters. + +mesher-angular-deflection +^^^^^^^^^^^^^^^^^^^^^^^^^ + ++--------+---------------------------------+---------+ +| Type | IfcConvert Option | Default | ++========+=================================+=========+ +| DOUBLE | ``--mesher-angular-deflection`` | 0.5 | ++--------+---------------------------------+---------+ + +Sets the angular tolerance of the mesher in radians. + +Here is an example in C++: + +.. code-block:: c++ + + SerializerSettings settings; + double tolerance; + // ... + settings.set_angular_tolerance(tolerance); + +Here is an example in Python: + +.. code-block:: python + + settings = ifcopenshell.geom.settings() + settings.set("mesher-angular-deflection", 0.5) + +mesher-linear-deflection +^^^^^^^^^^^^^^^^^^^^^^^^ + ++--------+--------------------------------+---------+ +| Type | IfcConvert Option | Default | ++========+================================+=========+ +| DOUBLE | ``--mesher-linear-deflection`` | 1e-3 | ++--------+--------------------------------+---------+ + +Sets the deflection tolerance of the mesher. + +Here is an example in C++: + +.. code-block:: c++ + + SerializerSettings settings; + double tolerance; + // ... + settings.set_deflection_tolerance(tolerance); + +Here is an example in Python: + +.. code-block:: python + + settings = ifcopenshell.geom.settings() + settings.set("mesher-linear-deflection", 1e-3) + +model-offset +^^^^^^^^^^^^ +---------------+--------------------+---------+ | Type | IfcConvert Option | Default | @@ -549,23 +612,102 @@ In Python, this is set in the settings passed to the iterator. .. code-block:: python settings = ifcopenshell.geom.settings() - offset = ifcopenshell.ifcopenshell_wrapper.float_array_3() - offset[0], offset[1], offset[2] = (1, 2, 3) - settings.offset = offset + settings.set("model-offset", (1.0, 2.0, 3.0)) -REORIENT_SHELLS ----------- +model-rotation +^^^^^^^^^^^^^^ -+------+---------------------+---------+ -| Type | IfcConvert Option | Default | -+======+=====================+=========+ -| BOOL | ``--orient-shells`` | False | -+------+---------------------+---------+ ++---------------+----------------------+---------+ +| Type | IfcConvert Option | Default | ++===============+======================+=========+ +| ARRAY | ``--model-rotation`` | 0,0,0,0 | ++---------------+----------------------+---------+ + +Applies an arbitrary quaternion rotation of form 'x,y,z,w' to all placements. + +no-normals +^^^^^^^^^^ + ++------+-------------------+---------+ +| Type | IfcConvert Option | Default | ++======+===================+=========+ +| BOOL | ``--no-normals`` | False | ++------+-------------------+---------+ + +Do not emit normals on geometric output. Saves time and filesize. + +no-parallel-mapping +^^^^^^^^^^^^^^^^^^^ + ++------+--------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+==========================+=========+ +| BOOL | ``-no-parallel-mapping`` | False | ++------+--------------------------+---------+ + +Perform mapping upfront (single-threaded) as opposed to in parallel. May decrease performance, but also decrease output size (in the future) + +no-wire-intersection-check +^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++------+----------------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+==================================+=========+ +| BOOL | ``--no-wire-intersection-check`` | False | ++------+----------------------------------+---------+ + +Disables wire intersection checks. These checks are done on faces to prevent +self-intersections of face bounds. Self-intersections reduce the reliability of +boolean operations and may lead to crashes. + +no-wire-intersection-tolerance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++------+--------------------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+======================================+=========+ +| BOOL | ``--no-wire-intersection-tolerance`` | False | ++------+--------------------------------------+---------+ + +Set wire intersection tolerance to 0. By default the above check is done using a +tolerance criterium. So that when a vertex is a certain epsilon distance away +from an edge this is flagged as an intersection. + +precision +^^^^^^^^^ + ++--------+-------------------+---------+ +| Type | IfcConvert Option | Default | ++========+===================+=========+ +| DOUBLE | ``--precision`` | 0 | ++--------+-------------------+---------+ + +By default the precision specified by the IFC model is used. You may set this to a custom precision. + +precision-factor +^^^^^^^^^^^^^^^^ + ++--------+------------------------+---------+ +| Type | IfcConvert Option | Default | ++========+========================+=========+ +| DOUBLE | ``--precision-factor`` | 0 | ++--------+------------------------+---------+ + +Option to increase linear tolerance for more permissive edge curves and fewer artifacts after boolean operations at the expense of geometric detail due to vertex collapsing and wire intersection fuzziness. This is multiplied to the precision. + +reorient-shells +^^^^^^^^^^^^^^^ + ++------+-----------------------+---------+ +| Type | IfcConvert Option | Default | ++======+=======================+=========+ +| BOOL | ``--reorient-shells`` | False | ++------+-----------------------+---------+ Re-orient or sew connected face sets to have a consistent outwards orientation. -SITE_LOCAL_PLACEMENT --------------------- +site-local-placement +^^^^^^^^^^^^^^^^^^^^ +------+----------------------------+---------+ | Type | IfcConvert Option | Default | @@ -573,35 +715,61 @@ SITE_LOCAL_PLACEMENT | BOOL | ``--site-local-placement`` | False | +------+----------------------------+---------+ -See ``BUILDING_LOCAL_PLACEMENT``, but exclude also the ObjectPlacement of the IfcSite. +See ``building-local-placement``, but exclude also the ObjectPlacement of the IfcSite. -STRICT_TOLERANCE ----------------- +surface-colour +^^^^^^^^^^^^^^ -+------+------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+========================+=========+ -| BOOL | ``--strict-tolerance`` | False | -+------+------------------------+---------+ ++------+----------------------+---------+ +| Type | IfcConvert Option | Default | ++======+======================+=========+ +| BOOL | ``--surface-colour`` | False | ++------+----------------------+---------+ -Strictly use the tolerance from the IFC model. Typically this value is increased -10-fold to have more reliable boolean subtraction results. It is recommended to -always have this set to True and should only be set to False for backwards -compatibility. +Prioritizes the surface color instead of using diffuse. -USE_BREP_DATA -------------- +triangulation-type +^^^^^^^^^^^^^^^^^^ -+------+------------------------------------+---------+ -| Type | IfcConvert Option | Default | -+======+====================================+=========+ -| BOOL | True for SVG, HDF, otherwise False | False | -+------+------------------------------------+---------+ ++------+--------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+==========================+=========+ +| INT | ``--triangulation-type`` | 0 | ++------+--------------------------+---------+ -See ``DISABLE_TRIANGULATION``. +Type of planar facet to be emitted. -USE_PYTHON_OPENCASCADE ----------------------- +.. code-block:: python + + settings = ifcopenshell.geom.settings() + settings.set("triangulation-type", ifcopenshell.ifcopenshell_wrapper.TRIANGLE_MESH) # 0 + settings.set("triangulation-type", ifcopenshell.ifcopenshell_wrapper.POLYHEDRON_WITHOUT_HOLES) # 1 + settings.set("triangulation-type", ifcopenshell.ifcopenshell_wrapper.POLYHEDRON_WITH_HOLES) # 2 + +unify-shapes +^^^^^^^^^^^^ + ++------+--------------------+---------+ +| Type | IfcConvert Option | Default | ++======+====================+=========+ +| BOOL | ``--unify-shapes`` | False | ++------+--------------------+---------+ + +Unify adjacent co-planar and co-linear subshapes (topological entities sharing the same geometric domain) before triangulation or further processing + +use-material-names +^^^^^^^^^^^^^^^^^^ + ++------+--------------------------+---------+ +| Type | IfcConvert Option | Default | ++======+==========================+=========+ +| BOOL | ``--use-material-names`` | False | ++------+--------------------------+---------+ + +Use material names instead of unique IDs for naming materials upon serialization. Applicable for OBJ and DAE output. + +use-python-opencascade +^^^^^^^^^^^^^^^^^^^^^^ +------+-------------------+---------+ | Type | IfcConvert Option | Default | @@ -613,11 +781,11 @@ USE_PYTHON_OPENCASCADE Only available in Python when an import of ``OCC.Core.BRepTools`` or ``OCC.BRepTools`` succeeds. -This implies ``USE_WORLD_COORDS`` and ``ITERATOR_OUTPUT`` set to ``SERIALIZED``. +This implies ``use-world-coords`` and ``iterator-output`` set to ``SERIALIZED``. The serialized TopoDS_Shape from iterator output is deserialized by Python OpenCASCADE. -USE_WORLD_COORDS ----------------- +use-world-coords +^^^^^^^^^^^^^^^^ +------+------------------------+---------+ | Type | IfcConvert Option | Default | @@ -627,8 +795,8 @@ USE_WORLD_COORDS Apply the ObjectPlacement of the building elements to the geometric output. This is implied when using the Wavefront .OBJ output in IfcConvert. Note that this also eliminates the possibility for geometric elements to point to the same interpreted geometry result. -VALIDATE_QUANTITIES -------------------- +validate +^^^^^^^^ +------+-------------------+---------+ | Type | IfcConvert Option | Default | @@ -640,8 +808,8 @@ Running IfcConvert with ``--validate`` will set a non-zero exit code when ever a Currently for internal use only. For every building element geometry converted, looks for an associated quantity set where the OwnerHistory's organization name is IfcOpenShell. And looks for the quantities "Total Surface Area", "Volume", "Shape Validation Properties.Surface Genus" and validates these according to the interpreted geometry definition. Emit Logger::Error when calculated values are outside of the tolerance range for the value stored in the model. -WELD_VERTICES -------------- +weld-vertices +^^^^^^^^^^^^^ +------+---------------------+---------------------------------------------+ | Type | IfcConvert Option | Default |