Package: nexus3d
ScopeThis is a project for reading out NXtransformation matrices from nexus files and
visualizing them by creating a 3D representation file (stlorgltf/glb- we recommend usingglb) which may be imported into 3D visualization software (e.g. blender). It is possible to load CAD drawings from stl files to visualize your experiment with it. For glb files you can easily visualize it in the web with three.js (see theexample)InstallThe easiest way to install is with pippip install nexus3dorpip install git+https://github.com/domna/nexus3d.gitfor the latest development install.If you want to keep to source code or use a development install clone the repostitorygit clone https://github.com/domna/nexus3d.git
cd nexus3dand install withpip install .from the cloned git repository or add an optional-eto install it in development mode.UsageExecutenexus3d nexus_file.nxson your nexus file to generate an output fileexperiment.glb.
The usage of the command is as follows:Usage: nexus3d [OPTIONS] FILE

  Create a glb/gltf or stl from a nexus file via the command line. The actual
  file format is chosen from the file ending of the output file (default:
  experiment.glb).

Options:
  -o, --output TEXT     The filename to write to.  [default: experiment.glb]
  -c, --config TEXT     Config file to load stl drawings into the final output
  -s, --size FLOAT      The side length of a cube in meters.  [default: 0.1]
  -f, --force           Force overwriting of output file.
  --include-process     Include transformations inside /entry/process
  --store-intermediate  Store the intermediate matrices in gltf child nodes.
                        Only applicable for gltf or glb files.
  --shape [cone|cube]   The shape to write into the gltf file. Only applicable
                        for gltf or glb files.   [default: cone]
  --blender             Rotates the coordinate system by 90 degree around the
                        x-axis. This maps the axes correctly to blender.
  --help                Show this message and exit.The optional config file in json format can be used to load stl files for the different objects, it should be according to the following format:{"instrument/my_fancy_instrument":{"file":"my_fancy_instrument.stl","x":5,"y":10,"z":3},"sample":{"file":"sample_holder.stl","z":3,"rot_x":90,"unit":"mm"},"instrument/detector":{"file":"my_detector.stl","unit":"inch"}}The json keys have to be named after their respective group containing a NXtransformation without leading/entry/.
Thefileattribute points to the stl file to be loaded.
Additionally, three keys (x,y,z) for translation (in meters) and three keys (rot_x,rot_y,rot_z) for rotation (in degrees) may be provided to introduce an additional shift and rotation of the stl drawing relative to
the coordinate frame from the nexus file. This is to account for any drawing offsets relative to the point denoted in the
nexus transformations. The shifts are introduced in the coordinate frame of the entry.
The rotations are applied first and then the object is translated.
Rotation are applied firstx, secondyand lastz.
The full chain is therefore
$$T  R_z  R_y  R_x  v$$
, applied to the vectorvin the coordinate frame of the entry.
To account for different units in the stl files a unit field may be provided.
The unit needs to bepintconvertible to meter.
If the unit field is not given meter is taken as default unit.Using with blenderThe exported glb or gltf files can be directly used with blender to have a proper visualization available.
However, please note that blender does a coordinate transform from glb/gltf files.
The mapping is:Blendergltf/glbxxy-zzyThis is equivalent to a rotation around the x-axis by 90 degrees.
There is also the--blenderflag which may be used to transform the coordinate system to be displayed correctly in blender.
However, in this case the coordinate system would be changed inside the gltf/glb file.Display in the webAn example forthree.jsbased rendering is available inexamples/threejs. It is based on thisexamplefrom three.js. The example can be directly viewed in the github pages of this project:https://domna.github.io/nexus3d/. To quickly view your model there exists the excellentgltf viewer, which also allows to adjust lighting and materials of your model.