topic Re: Import CGA rule from different CityEngine project in ArcGIS CityEngine Questions

Import CGA rule from different CityEngine project

KristianMortensen1 — Thu, 06 Oct 2016 08:40:04 GMT

Hello

I'm trying to create a CityEngine project where I want to add a facade to a building.

I have created the "Facade.cga" rulefile in a project called "Urb-Day" and now I want to use the same "Facade.cga" rule in another project called "stormwater".

I have tried to use the: import F_Facade: "Facade.cga" in the "Stormwater" project, and it works if the "Facade.cga" rulefile is located in the project "stormwater", but I would prefer that "Facade.cga" could be accessed when it is still placed in the "Urb-Day" project.

I think it is just the path to the facade.cga rulefile that is wrong, any suggestions?

Re: Import CGA rule from different CityEngine project

KristianMortensen1 — Sat, 08 Oct 2016 09:49:00 GMT

Thanks for that answer, then I will just have to adjust to workflow i had imagined.

Re: Import CGA rule from different CityEngine project

MatthiasBuehler2 — Mon, 10 Oct 2016 10:40:34 GMT

Hi all,

I'm adding a few more inputs to this. The answer provided is not completely correct.

CGA does support absolute paths and it is actually explicitly designed to do so. As the original post states, it's the goal to import CGA rules from OTHER PROJECTS.

Library projects such as the ESRI.lib are specifically there to provide rules that can be referenced and not as a resource for copy-pasting into every single project!

When doing absolute file paths, make sure you use the correct formatting:

/ProjectName/...

The first forward slash is the 'workspace root', short for 'workspace'. It is mandatory an absolute path starts with this slash.

CGA's drag and drop functionality should automatically create the correct paths. E.g. drag and drop a plant rule file from the ESRI.lib into your own CGA source code and check the line of code that is created for the 'import' statement.

Note why using this is very important:

Many CityEngine projects use the same assets, such as e.g. the plants. So copy-pasting all plants and street rules into every project we work with is a waste of space and makes versioning and project download times a nightmare.

Please push the 'library nature' of CityEngine, this is reason why both the ce.lib and the Esri.lib default projects are there.

Cheers!

Matt

matthias buehler || dipl. arch. eth zurich
------------------------------------------------------------------------------------------------------------------
vrbn bühler || www.vrbn.io || winterthurerstrasse 51 || 8610 uster || switzerland
+41 78 930 04 07 || matthias.buehler@vrbn.io || @vrbnio @mattb3d

Re: Import CGA rule from different CityEngine project

DavidWasserman — Mon, 10 Oct 2016 13:44:41 GMT

Hey Matthias,

As I reread the question, this is the far superior answer as it achieves the expected goal. Kristian, when I gave my answer I realized it sounded like I precluded the ability to import rules from other projects because I stated you should move the assets folder if you want to create a self contained project (I only suggested that because sometimes it is easy to forget). Please follow the instructions Matthias provide on importing rules with relative paths to other projects. I will say relative paths from the project folder are at least best practice, with common references in the documentation for some path functions * for asset paths.

That said, I think Matthias might have to clarify absolute paths in CityEngine.
Matthias, when I try the following for the lanes folder (All Forward Slash because \ common to windows is not recognized), the rule does not seem to find assets paths when they are absolute. This is the case if I put "/C:" or C: is removed along with other path components past CE install workspace as well.
*Edit: Based on the response below, using an absolute path based on the computer's root directory will never work in CityEngine.

*Edit: In CityEngine the example below would be an absolute path because it is relative to the CityEngine root directory. I previously mentioned it as a relative path.
-Absolute Paths- relative to CE Root directory and is project name dependent, if used for modular referencing it is assumed the project exists and its name space won't change. Have a / in front of them. This is how Esri.lib works for example.
EX: /Complete_Street_Rule/assets/....

-Relative Paths- relative to the project folder's rule directory.
- EX "Complete_Streets"

Is there a correct way to use absolute paths in CGA? Can you elaborate?

David

Re: Import CGA rule from different CityEngine project

MatthiasBuehler2 — Mon, 10 Oct 2016 14:06:42 GMT

Hi,

'Absolute paths' in CGA are always absolute to the workspace root, never the windows drive (e.g. C)
'Relative paths' in CGA are always relative to the project.

==>

Anything starting at the workspace root with a forward slash and the project name is an 'absolute path' within CityEngine, as CGA does not 'know' anything outside of the workspace.

Examples:

Referencing a rule from an other project:

"/Otherproject/rules/targetRule.cga" (= absolute path)

Referencing a rule from current project:

"rules/targetRule.cga" (= relative path. Note it is important not to have a '/' at the beginning, as CE would search for a project that is called 'rules'.)

Notes:

- I'd always avoid to reference assets from other projects with absolute paths (as project name changes force many rule changes).

- If you have absolute paths for rule imports in a projects, it's implied that specific other projects need to exist in the workspace. This is ok, as it allows modular project references.

- Note that CE has a heuristic that adapts the import statements if you change CGA rule names. This does not happen with project name changes.

Hope this helps!

Matt

------------------------------------------------------------------------------------------------------------------
matthias buehler || dipl. arch. eth zurich
------------------------------------------------------------------------------------------------------------------
vrbn bühler || www.vrbn.io || winterthurerstrasse 51 || 8610 uster || switzerland
+41 78 930 04 07 || matthias.buehler@vrbn.io || @vrbnio @mattb3d

Re: Import CGA rule from different CityEngine project

DavidWasserman — Mon, 10 Oct 2016 14:27:58 GMT

Thanks for clarifying the definition. So absolute paths in CE are those relative to the CityEngine workspace, and relative being to the working project rule directory. For most programming languages, I guess the confusion is that the master root directory is starting from a higher level root (C/Drive Name).
Thanks for correcting me Matthias.

Re: Import CGA rule from different CityEngine project

timrobinson — Thu, 13 Oct 2016 03:04:51 GMT

Hi Matt,

That advice about the Library functions is gold dust!

However, I've never come across this explained in any detail. It's certainly not in the Help File, and I can't find anything on the ESRI site, or recall anything on the old Procedural site that ever went over this.

It would be really good to know how the .lib spaces work. All I know is that ESRI.lib pops up in each workspace, and I had assumed that it was a behind-the-scenes mechanism not to be touched. For example, how can corporate teams set up a template project structure, or ensure that any new workspace includes corporate library files? I had not noticed any example rule files referencing the ESRI.lib, so had no idea that this could be done.

Any ESRI staff - can we get some further explanation on all of this please?

Re: Import CGA rule from different CityEngine project

DavidWasserman — Thu, 13 Oct 2016 04:48:15 GMT

Hey Tim,

The Complete Street Rule and some of the Rules in the Redland's Example reference Esri.lib assuming it will be available as a constant path in the CityEngine work space (chosen on installation). It is most common that the rule examples take the tree loader rule from Esri.lib for example.

Line Example:

import Tree : "/ESRI.lib/rules/Plants/Plant_Loader.cga" # Taken from ESRI.lib and uses its assets. Keep this in mind when using rule.

David

Re: Import CGA rule from different CityEngine project

timrobinson — Thu, 13 Oct 2016 23:54:59 GMT

Hi David,

Thanks for the reply! I guess I've just not noticed the presence of those lines in the Redlands or Complete Streets rules.

It would still be good to get an explanation as to the ins and outs of modifying the ESRI.lib or ce.lib content. Is it even advised?!

From Matt's reply above I get the idea that the lib content is encouraged to be used as a tool to avoid repeated copying in of resources - but what if we want to use more than just the very limited set of data in ESRI.lib for example? I'm just now aware of how to go about structuring such a resource tool, would be great to get some guidance from ESRI.

Re: Import CGA rule from different CityEngine project

DavidWasserman — Fri, 14 Oct 2016 01:22:43 GMT

Hey Tim,

Esri.lib does have all the default plant and some of the basic street rules that ESRI provides with it. The Esri.lib libraries likely have nothing stopping from having other rules and their assets added to their project folders for import and use in other projects. Edit*- Based on Matthias's answer below, while you might be able to use the libraries this way, these are low level libraries that get replaced on start up if they are not found. It would likely be best to make personal library like Tims_Library or something like that. Any change to the interface or folder structure of Esri.lib or ce.lib is not recommended as it could break the paths that a lot of rules depend on.
While I agree with Matthias's approach for managing CityEngine projects generally, if you need to share projects or distribute them, it makes sense to keep the assets of the rules you are using in the current project folder (UNLESS they come with CityEngine on install such as those in Esri.lib, in which call Esri.lib as the library it is intended). For example, for the complete street rule to be properly distributed, it requires its assets in the project so others can use it, but it does not require the plant's assets and rules because it expects the Esri.lib interface not to change (until it does, then I have work to do).

David

Re: Import CGA rule from different CityEngine project

MatthiasBuehler2 — Fri, 14 Oct 2016 09:31:01 GMT

Hi Tim,

Sorry I had login issues as I'm changing accounts currently.

David has already given a few inputs, but to add some 'more behind the scenes insight'.

ce.lib:

- Is a low-level library with some CGA stuff that is supposed to not be changed.

- If you delete this project, it will be recreated on CE startup!

- [ This project can be made visible in the Navigator, but that's not needed for typical users. ]

ESRI.lib:

- As the name implies, it's content provided in a black box. DO NOT CHANGE IT or add your stuff to it.

- Referencing files from other projects just technically works the same as referencing FROM the Esri.lib. 'By design'.

- If you delete the ESRI.lib project, it will be recreated with the default values on CE startup!

general:

Goal: create your own libraries for all the stuff you reuse often.

* * *

On a separate note on this topic:

@ David :

It's great to have the complete streets you put your work in ( and literally mention or refer to it in every single post ), but based on the technical discussion we've just had above, I believe you to should talk to our Esri colleagues to have your content pushed INTO the ESRI.lib. Why:

- It is confusing for users to see the distinction between what Esri and what other people provide and why they have to download e.g. all the plants twice, and so on.

- Streamlining the usability and proper integration in the above discussed 'LIBRARY' way of working would be helpful.

Again, thanks for all the hard work you provide for the community.

Re: Import CGA rule from different CityEngine project

DavidWasserman — Fri, 14 Oct 2016 13:04:37 GMT

Adjusted my answer accordingly. I knew altering any paths would be a bad idea. I did a quick test of adding something to Esri.lib showed it could be used that way, and it worked for a simple rule. However it definitely sounds like a bad idea. Best practice sounds like creating your own library projects.

I can talk to you more off the post about that idea, but the short answer is we are trying to find another distribution solution. There are currently multiple distributions of the complete street rule and it is very confusing...not all of them are current with bug fixes etc. The rule was released on an Esri Attribution license and my contributions are under an additional Apache license (I have both in the project I have). I'll email you about it.

PS: Hey you have your business card in every post, let me use the CS rule as a shameless example all of the place. XD Besides, I party on the other GIS threads too...

Thanks for the replies on this Matthias this has been helpful for me and the others on the thread.

David

Re: Import CGA rule from different CityEngine project

MatthiasBuehler3 — Fri, 14 Oct 2016 13:37:13 GMT

If GeoNet had any proper signatures, I'd use those. Any other forum offers a personal signature about who you are, so that's a different thing.

I tend to like more general examples instead of lots of screenshots that need a long description and explanation, that are kinda OT. But I see other people may 'shamelessly' (your words ..) prefer the other thing, hehe.

Re: Import CGA rule from different CityEngine project

CherylLau — Fri, 14 Oct 2016 13:48:39 GMT

Yes, it's true. File path info is either missing or really hard to find in the help pages. We'll try to add this info to the help pages. Thanks for pointing this out.

Thanks, Matt, for explaining it all quite well.

Re: Import CGA rule from different CityEngine project

DavidWasserman — Fri, 14 Oct 2016 13:49:51 GMT

I was kidding around. 😃 That makes sense.

Fair enough. Pictures are fun though.

Re: Import CGA rule from different CityEngine project

Anonymous User — Fri, 14 Oct 2016 17:13:26 GMT

Now that you all have explained how paths work inside of CityEngine projects and workspaces, I'll add another useful detail. Rules and assets can be easily packaged as a "rule package" (file extension RPK).

Right-click on a rule (.cga file), click "Share As...", then click Rule Package. The RPK file that is created bundles that rule, along with any imported rules, and any assets used by the rule. There will then be no dependencies on paths, absolute or relative. The RPK can be applied in any project, regardless of the existence of the original projects, such as ESRI.lib.

You can choose to "Include CGA source code", which allows users to see the rules and assets. This is what I do with all of my rules, so that others can learn from what I did right or wrong with the rule. The RPK is a zip file, and can be extracted to a folder, like any zip file (you don't need to change the file extension).

Also, RPKs can be applied as "symbology" in ArcGIS Pro. Similar to how a CGA rule is applied to a shape in CityEngine, in Pro, you can add the RPK to symbolize a feature layer, just like using a fill or stroke effect.

Note that importing some library rules, like the Plant_Loader, will include all of the assets used by that rule, which in the case of the Plant_Loader, will be 116MB of plant models added to the RPK. There are workarounds for this, which I won't go into here.

Hope this is useful for those who need to distribute a rule, without having to worry about what is in another user's workspace.

Chris