Import alignment from csv

[RickBrice]

This PR is an attempt to provide a quick and dirty mechanism to define alignment geometry in Bonsai. The idea is to define an alignment in a CSV file and import it. This is a temporary feature and will probably go away someday once I get a better handle on how to develop for Bonsai.

There is a new Alignment (.csv) command on the Import menu.

The CSV file format is:
X1,Y1,R1,X2,Y2,R2 .... Xn-1,Yn-1,Rn-1,Xn,Yn
D1,Z1,L1,D2,Z2,L2 .... Dn-1,Zn-1,Ln-1,Dn,Zn
D1,Z1,L1,D2,Z2,L2 .... Dn-1,Zn-1,Ln-1,Dn,Zn

The first row defines the horizontal alignment by the PI method. The circular curve radii R1 and Rn-1 are "placeholders" and are not used. A value of 0.0 is recommended.

The second and subsequent rows define vertical alignments by the PI method. D is distance along, Z is elevation, and L is the horizontal length of a parabolic vertical curve. Similar to the horizontal circular curves, L1 and Ln-1 are "placeholders" and are not used. A value of 0.0 is recommended.

Example:
Create a new project using the New Project Wizard. Use the IFC4X3 Schema
Select File > Import > Alignment (.csv)

Imported an alignment with two vertical profiles

[civilx64]

Nice - thanks!!! The humble alignment.py is ready to spread its wings so to speak and become part of the api.

I made suggestions on current year in the copyright headers but not certain if those actually should be updated.

General suggestions for follow-up:

• lint with black
• docstrings for everything in the api (including examples)
• unit tests for the alignment api using the FHWA data as example

Some of these may be good candidates for tasks to put on the infra authoring project backlog.

[Moult]

Regarding copyright changes I think sooner or later a script that parses git logs per file and updates the copyright dates is probably something we should do project-wide.

[RickBrice]

Thanks for the feedback. Looks like I’ve got some work to do before this is ready for prime time.

[RickBrice]

@civilx64 I've been doing a lot of refactoring of the API - it is way more granular now.
How do I test the documentation? I've been adding docstrings for all the functions.
You can see what I've been up to in https://github.com/IfcOpenShell/IfcOpenShell/tree/RAB_alignment_api/

[Moult]

You may need to add your module to the list of modules in `bim/__init__.py`

[Moult]

See https://docs.ifcopenshell.org/introduction/how_to_contribute.html#writing-documentation

[civilx64]

@RickBrice apologies; it looks like my docstring exmples are using a different (possibly obsolete) syntax. The previous ifcopenshell.alignment docstrings get rendered rather messily:

when compared to other parts of the docs

See this example for correct syntax in the docstring and the corresponding reference documentation.

If the parameters and return types have python type hints - like this copy_class example - then you should be able to omit the :type: and :rtype: info in the docstring.

Lastly you should be able to use the doctest module to test any example code in docstrings. Full disclosure - I have never utilized this myself.

LMK if you need some help with the busy work I created of reformatting @param: to :param:. Maybe it will be a quick find/replace?

[RickBrice]

I'm done a huge amount of refactoring and response to your comments.
I still need to clean up the documentation and implement additional unit tests.
Your review is requested.

[RickBrice]

@Moult I have updated the basic documentation for the Import > Alignment comment. I have two questions for you regarding documentation

1. Where would be a good place to explain the expected values in the alignment CSV file? I couldn't find anything similar for the Cost or Work Schedule imports to use as a guide.
2. I want to update the image that shows the import functions. I found the style information document (line color, point size, etc), but I am uncertain as to how to create the circle, line, and rectangle with the color gradient. Is there some step-by-step instructions on how to do this with something like Gimp? I'm not at all versed with Gimp so after an hour I had to give up.

[aothms]

Looks good to me. Really amazing to see the first contours of infra authoring.

Did you have a look at the failing tests:

I'm a fan of pytest.approx:

assert mapped_segments[0].SegmentStart.wrappedValue == pytest.approx(1991.601501867533)

The [0] index is maybe a bit unclear that this is the 0th attribute of the direction instance. Maybe just use DirectionRatios but I'm guily of this myself frequently as well when I'm not patient enough to look up an attribute name. Anyway, just compare to a 2d vector instead.

[RickBrice]

@aothms I updated the unit tests to use pytest.approx() as suggested. I am having difficulty reconciling the test errors. I don’t think I caused any of the mathutil errors. For geometry settings, I added a new setting, compute-curvature, but don’t know how to update the test for the new setting. There is another setting error related to cgal, and don’t think it is related to my changes. Please advise

[Moult]

Where would be a good place to explain the expected values in the alignment CSV file?

Anywhere in here is fine: https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.8.0/src/bonsai/docs/guides - we can always reorganise it later but content is king :)

I want to update the image that shows the import functions.

I don't have a good answer for this, because image editing takes time and a pixel-perfect attitude to give off a good impression for official docs, but it's also something that we don't have much time for. Perhaps gradiented boxes is too hard. Maybe just file a bug and let someone else help?

[RickBrice]

@aothms i fixed all the unit tests related to my changes. The remaining failures seem to be related to mathutils. Is there something more I need to to do?

@civilx64 any additional comments? If not, I think this PR is ready to merge.

We will have a simplistic method of defining an alignment and a starter API.

[civilx64]

I took a final look over everything - very impressive! Just one typo and an FYI.

[RickBrice]

@Moult I think I messed up with this PR. I merged this branch into the v0.8.0 branch because I thought everything was good to go.

I have my Bonsai setup so it uses the latest build from the raw.githubusercontent.com repository. When I updated and tried to use the new alignment from CSV feature it crashes (traceback is below). The alignment feature depends on changes made in IfcOpenShell. Specifically, there is a new geometry setting to compute curvature on an alignment curve.

Sorry I messed this up. How can the problem be resolved?

Traceback (most recent call last):
  File "C:\Users\rickb\AppData\Roaming\Blender Foundation\Blender\4.3\extensions\.local\lib\python3.11\site-packages\bonsai\tool\ifc.py", line 316, in execute
    IfcStore.execute_ifc_operator(self, context)
  File "C:\Users\rickb\AppData\Roaming\Blender Foundation\Blender\4.3\extensions\.local\lib\python3.11\site-packages\bonsai\bim\ifc.py", line 458, in execute_ifc_operator
    result = getattr(operator, "_execute")(context)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\rickb\AppData\Roaming\Blender Foundation\Blender\4.3\extensions\.local\lib\python3.11\site-packages\bonsai\bim\module\alignment\operator.py", line 67, in _execute
    ifcopenshell.api.alignment.create_geometric_representation(self.file, alignment)
  File "C:\Users\rickb\AppData\Roaming\Blender Foundation\Blender\4.3\extensions\.local\lib\python3.11\site-packages\ifcopenshell\api\alignment\create_geometric_representation.py", line 129, in create_geometric_representation
    ifcopenshell.api.alignment.map_alignment_segments(file, layouts[0], composite_curve)
  File "C:\Users\rickb\AppData\Roaming\Blender Foundation\Blender\4.3\extensions\.local\lib\python3.11\site-packages\ifcopenshell\api\alignment\map_alignment_segments.py", line 62, in map_alignment_segments
    ifcopenshell.api.alignment.add_segment_to_curve(file, mapped_segment, composite_curve)
  File "C:\Users\rickb\AppData\Roaming\Blender Foundation\Blender\4.3\extensions\.local\lib\python3.11\site-packages\ifcopenshell\api\alignment\add_segment_to_curve.py", line 73, in add_segment_to_curve
    ifcopenshell.api.alignment.update_curve_segment_transition_code(prev_segment, segment)
  File "C:\Users\rickb\AppData\Roaming\Blender Foundation\Blender\4.3\extensions\.local\lib\python3.11\site-packages\ifcopenshell\api\alignment\update_curve_segment_transition_code.py", line 51, in update_curve_segment_transition_code
    settings.set("COMPUTE_CURVATURE", True)
  File "C:\Users\rickb\AppData\Roaming\Blender Foundation\Blender\4.3\extensions\.local\lib\python3.11\site-packages\ifcopenshell\geom\main.py", line 185, in set
    self.set_(self.name(k), v)
  File "C:\Users\rickb\AppData\Roaming\Blender Foundation\Blender\4.3\extensions\.local\lib\python3.11\site-packages\ifcopenshell\ifcopenshell_wrapper.py", line 486, in set_
    return _ifcopenshell_wrapper.Settings_set_(self, *args)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
RuntimeError: Setting not available

[civilx64]

@RickBrice Did you recompile the C++ extension wrapper as well? If so is it linked to the blender python environment?

My hunch is that you didn't actually break anything. I don't think the daily releases include new compilations of the C++ wrapper.

[RickBrice]

I can compile the C++ and copy the wrapper pyd and py files into the bonsai site-package\ifcopenshell folder and everything works.

My concern is that if someone updates bonsai with the latest build and tries to use the alignment import feature, it won't work.

Some how ifcos needs to be recompiled and packaged with bonsai.

[civilx64]

Some how ifcos needs to be recompiled and packaged with bonsai.

It will be, just takes a few days to a week for the wrapper to catch up. CI/CD for the C++ gets kicked off manually, I believe.

@aothms do I have that right?

[aothms]

Yeah occasionally we have this as part of our imperfect distribution process. You can code more defensively with try-catch for this transition window, but that's also ugly later on. Most people in the community are used to this... I've started a new build.

[RickBrice]

Thanks. I was afraid I made a major blunder on my first step into the Bonsai side of things.