Neuron Building ZScript


I am exploring writing a zscript to import data from an ASCII text file, and build geometry in ZBrush. The data is on neuron structure from research studies, and is in a very basic form where, after some metadata, each line contains:

an index, a structure identifier, x,y,z coordinates, radius, and the index number of the “parent” node

A typical file might look like this:

SWC to SWC conversion from L-Measure.

Original fileName: foo.swc

1 1 27.03 -103.54 -4.15 20.6075 -1
2 1 27.03 -82.93 -4.15 20.6075 1
3 1 27.03 -124.15 -4.15 20.6075 1
4 3 10 -112.5 -14.5 2.6 1
5 3 1.5 -114 -17.5 2.45 4
6 3 -3 -115.5 -21 2.45 5
7 3 -19 -105 -21 0.85 6
8 3 -50.5 -87.5 -28.5 0.85 7
9 3 -119 -53 -52 0.7 8
10 3 -129 -48 -56.5 0.65 9

It strikes me that this information maps very well to creating a ZSphere model.

I’ve done this previously in python for another 3D package (https://github.com/NWoolridge/NeuronBuild); python’s string handling is very good, though, and I wasn’t sure whether in zscript I can:

  • count lines in an input text file

  • ignore comment lines (#)

  • traverse lines using space as a delimiter

Please forgive my ignorance, but I haven’t been able to figure this out from the zscript commend reference. Thanks!

That’s an interesting idea! Though I’m not sure if you will encounter problems creating a large number of zspheres…

ZScript handling of strings is rather limited but what you want is perfectly possible with a little ingenuity. I’ve attached an example script that I hope helps.

Let us know how you get on!

Wow, thank you so much for this help! I’m sure it would have taken me a long time to get as far as you have in this very useful code sample…

Hi Marcus,

I’ve been working on this, based on your excellent sample code, and I have couple of questions:

  • So far, I have only been able to get the script to work (to the extent that it does), by running it after having already created a ZSphere and entering edit mode; is there a way to do this programatically?
  • So far, the build results I am getting do not match the geometry you should see; the zsphere placement in space and parenting is not correct. I think this has to do with the fact that the last value in each line of the input data is not assigned correctly to the SWC_ValuesMem variable: if the value is less that “10”, it is set to “0”; if it is above “10”, it is set correctly. I’m not sure how to fix this…
  • So far the resulting ZSphere setups are “pathological”; any attempt to adaptive skin them, or do anything really, result in an immediate program crash. This is perhaps because of the previous issue…
  • If ZSpheres are too problematic, is there a better way to draw the cylindrical branching required here? Can a brush be scripted to “paint” the geometry into place with a varying radius?

I’m attaching the script in its current form, and a test data input file, and an OBJ file that shows wat the geometry should look like, more or less…

Any help would be most appreciated!


I’ll look closely at what’s happening when I have a moment but I think it should be possible to get this working. (Though whether it’s possible to get a really clean mesh remains to be seen…) There’s something strange going on with your file example that I’ve yet to solve. There’s also a general issue of scale - it’s necessary to reduce the size in order not to hit a limit where everything gets truncated. But I got this result with a file I downloaded from the site you give:

That looks very promising… and thanks for following this up! Do you happen to know which file you chose? I can check it to see whether this is the expected topology…

What scale factor did you use to keep it within a reasonable size?

I’ve also been think that ZSpheres may not be the best modelling approach. Creating curves meshes may be better, though I’m not sure you can taper those programatically…

Many thanks again!

Here’s the file:

I used a scale factor of 30. But it needs to be calculated on a per-model basis. Put in 20 and you’ll see the result!

What did you change in the script to get to that point? Did you add a “scale factor” variable and divide all the dimensions by that?

Many thanks for following up with this…

And what do you think would be the best geometry approach, because even with the successful zsphere model, there doesn’t seem to be a way to get a usable mesh from it without crashing ZBrush…

Here is the modified script. This works for me. It includes hack for getting the scaling factor and also loads the zsphere as necessary. I don’t get a crash when previewing the mesh but the file you posted has issues with stray points/zspheres.

I don’t know that there’s another way of doing this within ZBrush. It’s possible to create curves but I think that would be a difficult route and in the end one might as well construct an OBJ using a DLL.

Hi Marcus,

This is remarkable! Thank you. You even solved the problem of it needing to be in edit mode with a zsphere in the scene. Bravo!

I still find that I get an immediate Zbrush crash if I preview the adaptive skin. If however I change The adaptive skin settings to “use classic skinning”, then it does not crash and I can generate a mesh.

Would you be OK with me redistributing this to the medical illustration and science visualization communities? You are responsible for more than 90% of the code in the script, and I would like to make sure that you receive appropriate credit. My intent would be to make it available on an open source code sharing site Like github. I will try to polish it up a little and create tutorials on its use.

What do you think?

Yes, do share the script if you wish. If anyone comes up with any interesting illustrations as a result do please post them in the Main forum. It’s always interesting to see what people are using ZBrush for! And if I think of any improvements I’ll post them here.

Hi Marcus,

Great! How would you like to be credited? As “Marcus”? or “Marcus_civis”? Or something else? Is it OK If I put in something like ©Marcus and Nick Woolridge (it will be open source).

I am planning on making some changes to the script:

  • to add instruction comments and an MIT License (the simplest free and open source license I could find)

  • I may add an option to either scale the size down by a known amount, or to embed a cube of known scale, since preserving the relative scale of these structures is important for scientific illustrators.

I’ll dm you the proposed verbiage, and please let me know if you have a problem with any of this…

You might consider making it into a plugin. The script doesn’t have to be installed - the file can be loaded in the same way - but the buttons will appear in their own sub-palette in the interface, and not disappear if the user uses another plugin.


That’s a good idea… I’ll look into it… and probably bother you for help again…!

Hi Marcus,

I’ve uploaded the script (along with its C4D counterpart) to Github at:


And added a video on using it at https://vimeo.com/207323832

Many thanks again for your incredible help and interest!

Good stuff. :+1: Thanks!