Search

Data Preparation Before we start getting into the preparation of data, let´s first get out of the way a common misunderstanding : Shape is not a software that processes observational data and as a result delivers a 3-D model. What Shape does is to provide you with a set of tools that allow you to apply your scientific insight and creativity to generate a 3-D model that reproduces your data as closely as possible. During this process you might improve your understanding of the object of your research and with the final model you have a tool to help your peers to better understand your conclusions. Selected Window: Data as a reference in the Render Module are included per Window , which may be an Image or a Position-Velocity (P-V) window. Clicking on a Window selects that window , which is indicated by a thicker white border of the window. Once a window has been selected, the drop-down list at the top of the Properties tab gives access to the selected window by chosing Selected Window . Two important choices to be made at the top are the flags Render and Master . By default all windows get rendered, but sometimes it may be prefereable to not render some windows. Only one of the windows can have the Master switch on . Once you select Master for a window, the corresponding switch in the previous Master window is switched off. The Master switch determines which rendered or reference image can be shown in the Render View of the 3-D Module as a reference background during the modelling process. The potential of cross-checks between data and models : It has happened in several occasions that the model result hinted at problems with the data processing and resulted in the correction of mistakes. Hence, frequent critical cross-check between data and model can be beneficial in both directions. Usually the data inform the modeling process. Occasionally it also happen that the modelling leads to corrections , new processing or interpretations of the data . Data Preparation: Data for Shape basically consist of some form of image that is placed as a reference in the background of the rendered images, spectral images or the 3-D views in the 3-D Module. Shape provides tools to correctly place the images in their corresponding context. The key information that is needed to prepare these images are their scaling and corner positions in the chosen coordinates. So, for instance, if you wish to work on arcsecond scales and your side to side field of view is 10 arcsec, then you have two options . First, you crop your image to the same field of view. Then, after loading it into Shape, it fits automatically to the 10x10 arcsec field that you have set up. This is the recommendable option . The second , more complex, but often necessary option is to use a certain image as it is. Then the position, rotation and size are adjusted in Shape such that it is correctly placed in the field of view. These options are applicable for images, P-V diagramas, channel maps and graphs. If your images have scales with tick-marks , you can adjust the placement such that they coincide with the corresponding tick marks in the Shape image coordinate system. This can be done in position and velocity. In the first example on the right (click on the image to see a larger version ) the observed image was first cropped to a square format that corresponded precisely to the original size of the default window size or range values. As long as no rendering was done, the background image remains visible. The visibility of the background image is indicated by the red square in the top-left corner . Once your models become very realistic you may not immediately notice whether you are looking at the observed or rendered image. Then it may happen that you are wondering why your rendering hasn´t changed after your changes in the 3-D model settings... until you notice that there is a little red square that tells you that you have been staring at the observed image all the time. To gradually switch between reference and rendered image use the Transparency slider . In the second example on the right, a new P-V Window was added. A single position velocity diagram as shown further up was added as a background. The x0, y0, x1, y1 values were adjusted such that the image fits precisely in such a way that the tick marks in the observed image and render window overlay correctly. A small additional correction was applied by adding a Translation Modifier to the observed image with an adjustment in the x-direction. Other modifiers can be added to correct scaling and rotation of the reference image . Note that the order of the modifiers in the stack may be important, especially when there are rotation and translations combined. Rendered images as references for changes: Often one needs to compare a previous rendering with the one that includes new changes to the model. Rendered images can be saved as reference images after you open the background Image drop-down list and select None . Then click on Save image. A new item in the image stack appears labeled with the time the image was saved. A whole sequence of rendered reference images can be build by repeating this process. To delete an image from the stack, select the image and press Remove image .

Render Module Properties Panel: General Properties Panel: General The initial panel contains the General properties of the 3-D volume that is going to be generated and the type of rendering algorithm that is going to be employed. Resolution: The number of volume elements (voxels) that the computing domain is to have in each direction. The total number will the N^3. Note that the rendering time required therefore increases very quickly with this number and your system may run out of memory. Make sure Shape is run with sufficient memory allocated for the process at startup. Scene size: The width of the computing domain in terms of physical units, which by default is meters (m). This number corresponds to half the voxel size assigned to the Resolution parameter above. The physical domain runs from -(scene size):+(scene size). Scene center: The center of the cubic computational domain may be shifted in the physical scene that might be larger than the rendering domain. Setting a smaller domain with a shifted center may be useful for testing purposes or for achieving higher resolution outputs for certain regions. Renderer: Choose the type of renderer from this drop-down list: either the High-Definition (HD) render (default) or the Standard renderer (SD). The HD renderer does not use a predefined cubic voxel grid and works similar to a ray-tracing engine that integrates to the pixel plane. If there are computations that depend on light sources, such as dust scattering, it is computed along the way. This may require more time, but is much less memory intensive. Therefore higher resolutions can be achieved. Fast renders, e.g. for camera animation movies, is not possible, however, since the some information is not stored for quick rendering from the precomputed voxel grid. Grid: When the HD render mode is switched on and scattering or photo-ionization processes are to be calculated, you can activate the Grid flag to use a grid for the scattering and ionization calculations. This speeds up the computation, but may be less accurate and uses more memory, which may limit the resolution on systems with insufficient RAM. For the most accurate calculation make the grid the same size as the Resolution parameter. Smaller sizes are best set smaller by factors of 2. They speed up the computation, but are less accurate. Grid Size: When the Grid flag for the HD renderer is set, then you can choose the size of the grid with this parameter. Make sure it is not larger than the Resolution parameters. Step Size: The ray casting and ray tracing step size in units of the cell size of the domain. Setting it smaller than 1 can in some cases yield somewhat better accuracy. It does, however, take more computing time. Jitter: As an anti-aliasing method you can randomly displace the rays from the center of the image pixels. This is in units of the pixels size. # samples: The number of samples, i.e. rays to be cast, for each pixels. The position of the rays in a pixels are random. This may be used to increase accuracy slightly or as a measure to reduce aliasing. Auto render: If the HD is off or the Save grid flag is on, then data of the full grid have been saved and can be used to quickly render the scene for different camera views and animations. When you change the parameters of the camera the rendering updates automatically. The effect is not "real time" and may take a few seconds, depending on the resolution. Use window: For quick render in HD mode that require only a small portion of the image to be rendered, you can set a window using the Window Button above the image. Click on the icon with the square and then drag out a rectangle with the left mouse-button pressed. If the Use window flag is on, only this region will be rendered. This reduces the rendering times during model development when it is sufficient to see only part of the model. Overlay: Occasionally it is convenient to retain the previous image or images and add progressive images together. This is useful for diagnostics or simply as a nice "special effect.

The Bump Modifier is designed to add individual bumpy extrusions to a mesh. Position, orientation and detailed shape of the bump can be controlled. To add a Bump Modifier to the Modifier Stack, click on the Add Modifier button (the + sign under the Modifier Stack) and select Bump. The modifier appears at the end of the stack. It is important to note that the detailed effect of the modifier may depend on the position within the stack. Therefore experiment how it interacts with other modifiers before or after in the list. Different properties of the Bump Modifier is controlled in different places. The Control Panel under the Modifier Stack has several check marks: Enable: Enable or disable the Bump Modifier Symmetric: By default the bump will be cylindrically symmetric around its direction axis that can be seen when the Widget is on. Then the check mark is on. When the Symmetric flag is off, then the bump will be infinite in one direction and controllable in the other. Radial: When the Radial flag is checked, then the bump will be applied radially from the coordinate center of the Widget. Otherwise it is parallel to the directional axis (pink) of the the Widget starting in the plane that contains its coordinate center. Widget: Posititon & Orientation The position and orientation are controlled with the Widget. The numerical control panel for the Widget can be opened by clicking on the Widget button in the Control Panel. Alternatively, use the interactive Widget controls on the left side of the 3-D views. As usual, during interactive control use the x, y and z keys to restrict moving and rotating actions to a particular axis. Magnitude: Shape & Size The shape and size of the bump are controlled from the Magnitude Graph that is accessed in the Control Panel under the Modifier Stack. The Magnitude Graph works the same way as other graphs in Shape. For details see the user manual entry for Graphs . The shape of the bump is set using an Analytic function or a Point graph, where the "x" is the distance from the local coordinate system (widget axis) is cylindrical coordinates. For the "symmetric", i.e. cylindrically symmetric case, the values at negative x are ignored. By default the shape of the bump is set to a Gaussian function. The overall size of the bump can additionally be controlled using the f0 parameter in the top left corner. Magnitude: Change the bump structure The detailed shape of the bump can be arbitrarily complex. This can be achieved by changing the Analytic function as shown in the examples on the right. Alternatively, for even more arbitrary complexity use the Point function by clicking on the Function drop-down list. Edit the Point function following the instructions in on the Graphs page . Mesh resolution: Note that the application of the Bump Modifier may lead to poor mesh resolution in the bump. Currently the mesh resolution can not be improved locally. Therefore, if necessary, the overall mesh resolution can be increased by increasing the number of Segments in the Primitive tab of the object. Modifiers: Bump

Wix Forum is no longer available This application has been discontinued. If you need community app use Wix Groups.

Render Module Properties Panel: Selected Window Properties Panel: Selected Window The Render Module can have several render windows, which can be of type Image or P-V (Position-Velocity). Each of them may have different parameters, which are listed and managed in the "Selected Window" panel. The selection is done by right-clicking on a window . The selected window is then highlighted by a white boarder that is thicker than that of the others. The parameter panel changes automatically when you change the selected window. While there are some parameters that they have in common, the Image and the P-V windows have different sets of parameters . First we will discuss those of the Image window . Then we describe the additional parameters that correspond to the P-V window. The common parameters will not be repeated here . 2D Image Render : This flag determines whether this window is to be update after the next rendering process (on) or shall keep the previously rendered image (off). By default this flag is set to on. If you have several image windows, it may be desirable to keep the previous result to compare with another window that is updated. Master: If you use the data of an image in an other module , this can be done only for one of the image windows. The one that is used is the one with the Master flag on . When you change the flag of one window from off to on, then the window that previously had the Master flag on is automatically switched off. Window Parameters: Under the Master flag there is a group of four icons that invoke utility commands . The first one copies the window parameters into a buffer . If you have additional windows of the same type and want them to have the same initial parameters, then you use the second button to paste the buffered window parameters to another window (after selecting it by clicking on the window). The third button saves the image of a window to file. Note that you need to provide the filename with the appropriate extension, e.g. .png. Shape selects the format of the image file according to the file extension that you provide. The fourth icon lets you print the image of the window to a printer or save it as a file in PDF format . It basically embeds the image in a PDF-file. Note that the image annotations, such as coordinates are not saved in a separate scalable font, but are incorporated in the pixelized image. Seeing: The combination of image degradation from atmospheric seeing and instrument resolution is simulated by a convolution of the image with a Gaussian kernel with a full-width half-maximum (FWHM ) of this value. It uses the same units as those chosen in the Units Panel of the Render Module. Slits: The slits drop-down list contains the slits that correspond to the P-V windows. In this list they can be switched off from this image window by unchecking them. If the "Move Slit " button above the image window is on, you can click on a slit and move it by pressing the left-mouse button and dragging it horizontally. After clicking on a slit and then moving the mouse-wheel, the slit-width can be changed interactively. The color of a slit helps to identify the P-V window to which it corresponds. The P-V window has a thick vertical line of the same color. Background Image: This section of the Selected Image Window Panel controls the file, positioning and appearance of the reference image that is loaded into the background layer of the image display. Image: From this drop-down list the current background image is selected. By default it is the "Observed" image, which can be loaded from file. Initially there is one other option called "None", which displays no image. However, when the None option is selected, the currently rendered image can be added to the list as a reference to be compared to later renders. It is often useful to compare renders from changed parameters with the previous version to see the effect of the parameter change. When selected, a button appears that allows one to delete such an image from the list when no longer needed. Transparency: In order to interactively compare the rendered image with the background image, the transparency of the rendered image is changed using the slider. If the slider is moved to the right, the transparency increases and the background image gradually appears. To help identifying whether the rendered or the background image is visible, the background image is marked with a red square in the top-left corner. Filename: The file path and name of the Observed background image. Click on the icon on the right of the filename field to select a file from disk. x0, x1, y0, y1: The coordinates of the bottom-left (x0,y0) and top-right (x1,y1) corners of the observed image. If all values are left at 0 (default), then the image fill the current image range. Setting custom values allows a precise placement of the image. Modifiers: The appearance and positioning of the Observed image can be adjusted using various operators, called modifiers. They can be selected from the "Available Modifiers" drop-down list. It is then added to the Modifier list that is applied to the image. Each of them has it´s own set of parameters, which in most cases are self-explanatory. PV Window The first few parameters of a P-V Window are the same as those of an Image Window. Please refer to that section above for an explanation. Slit color: In many projects data for several slit positions are available. To more easily relate them with the slit marking in the image window and the parameter panel, you can set individual slit colors. Default colors are assigned randomly. Slit X, Slit Y : The horizontal and vertical position of the slit, respectively. It can be set numerically in this field or interactively with the mouse cursor by dragging the slit on the Image Window. Make sure to activate the "Move Slit " icon above the Image Window first to enable the interactive functionality. By default the slit can only be moved horizontally. To interactively move it vertically press "y" at the same time as you drag it up or down. Slit width, Slit height : The slit width can be changed interactively after activating the "Move slit" button above the Image Window using the mouse wheel. By default the width is changed. If at the same time you press the "y" key , the height of the slit is changed interactively. Naturally, you can also change the values manually in the number fields. Velocity : The reference velocity for the spectroscopy is set in the "Spectrum " section of the Render Module. In the scale of the P-V window the zero-velocity for the graph can, however, be shifted by the value of this parameter. I maintains the same total range as before . Range : The total width of the P-V Window in units of velocity. Resolution : The P-V image is convolved with a Gaussian kernel of this full-width half-maximum (FWHM ) in horizontal direction in units of velocity. Background Image : This section is similar to that for the Image Window as described above. Please refer to that section.

The Texture Displacement Modifier uses a procedural texture to deform a mesh. The value of the 3-D texture at position of a mesh vertex in space determines how far the vertex is pushed away from its original position. The magnitude of the position change of the vertex as a function of the grey value of the texture. The direction can be chosen to be radial (set the radial flag) from the local coordinate system or you can use the widget to set the direction. The Magnitude dialog: In the Magnitude dialog you set the function that determines the distance a vertex is pushed based on the grey-scale value of the texture at its original position in space. The values of the texture is in the range [0,1]. The variable that carries these values is "x". So, if you use the default "x" as a function, the vertices will move between 0 and 1 units. The example mesh show in the figure below uses a "clumpy" texture with a few hundred clumps distributed in the spatial domain. The function that is used as magnitude of the displacement is 15*(x-0.5). The reason we subtract 0.5 from x is to allow the texture to not only push outwards making the shell necessarily larger, but also inwards, such that the average radius stays approximately the same. The factor 15 then extents the maximum range for the displacement to that value. Texture : Use the Texture dialog to choose and customize the texture that controls the Texture Displacement modifier. See the page on the Texture key subsystem for information on how to setup a texture. Modifiers: Texture Displacement

Radiation Transfer The mathematical description of the radiation transfer physics used in Shape is described in the following PDF document.

Overview The mesh objects serve as containers of density and limit the volume where the density of an object is placed in space. The density modifier controls the density distribution within the volume fixed by the mesh container. Several other modifiers work in exactly the same way as the density modifier and are therefore not treated separately. These include the temperature and the pressure modifiers . In addition to the common parameters for naming and enabling modifiers, the density modifier has the following parameters: f0: factor that scales the density that is otherwise controlled by the 3-D distribution defined in the Magnitude graph (see below). It is actually part of the Magnitude graph, but because of its frequency of use it is also exposed at this level of the panel. Sigma: currently not in use Operation : This is a drop-down list with the options: Replace, Add and Scale . These are the operations that will be used to determine how this density modifier affects a possibly existing sequence of density modifiers further up in the modifier stack. Replace mode: The first density modifier should be used in Replace mode . If there is a density modifier further down in the stack in Replace mode, then all previous density modifiers have no effect and only this one and those further down in the stack are used. Add mode: the density of this modifier is added to whatever is the result of the previous density modifiers in the stack. Scale mode: the density of this modifier is added to whatever is the result of the previous density modifiers in the stack. In the example on the right there are three renderings of the same geometrical object with density modifiers as shown in the stack above the rendered images. The first image has a density with a point graph that changes as a function of the z-coordinate in cylindrical coordinates. See the graph below the rendered images and note that the Coordinates have been set to Cylindrical. This density modifier is label Ladder Strungs. It is located at the top of the modifier stack and is in Replace mode . The second density modifier is labeled Global Decay and is in Scale mode retaining the default Spherical Coordinate system (see the second modifier graph under the rendered images). It scales the density that results from the first modifier with a normalized Gaussian as a function of distance. In the final example, a Texture was included in the first density modifier. The texture scales this modifiers with the three-dimensional procedural texture of which a slice is shown below. How textures work in more detail is explained in the corresponding section of this manual on Textures. Modifiers: Density (Temperature, Pressure)

Top of Page Overview General Considerations Computing Power Batch Processing Typical Modeling Applications Morpho-kinematic Modeling Photo-realistic Models 3-D Hydrodynamics Exoplanet transits Schematic illustrations Basic Workflow Need a new ShapeX feature? . Overview General Considerations Overview Your first question is likely to be: Is Shape suitable for my modeling problem? Here is a short summary of the types of problems that have been worked on with Shape and others for which we know that the software can be used. We shall also discuss the limitations that might prevent your problem to be attacked with Shape. General considerations: Polygon meshes: Polygon mesh objects are the most basic building blocks in Shape. The software generates them in a similar way as common 3-D animation programs such as the open-source Blender and many other commercial packages. However, these programs have been designed to model mostly opaque objects that surround us and hence compute their visual appearance according to the color assigned to their surface as a function of position and the lighting conditions. Only exceptionally volumetric effects are computed for clouds, fire or other phenomena that are not opaque. In astronomy and astrophysics almost everything is about gas and dust clouds that are at least partially transparent. Real surfaces are very rare and can be found only on rocky planets and other solid bodies. Some stars can be considered to have "surfaces" since the transition from the optically thin to thick regimes is very small compared to their size. The polygon meshes in Shape are therefore mainly used as containers of gaseous or dusty volumes, which are then assigned physical properties as a function of position within that volume rather than on the surface. Computing Power Batch Processing Computing Power: An old saying claims: "There is no such thing as too much computing power." This is also true for Shape applications that wish to push the limits of what is possible. But for many scientific applications today´s power of almost any laptop suffices. Since Shape is a highly interactive software, for your own comfort and an effective workflow make sure to use a mouse instead of just the mouse-pad. More sophisticated devices such as graphics tablets are of additional benefit for some applications. Most processes in Shape make use of parallel computing on multi-core CPUs. Especially the rendering processes and hydrodynamic simulations benefit from many-core CPUs and multi-threading. While the benefit of parallel computing mainly lies in reducing the time required for a computation, memory influences the spatial resolution that can be achieved in a rendering or hydrodynamic simulation. So, if you have ambitions to produce high resolution photo-realistic visualization and animations, then you might want to use a high-end workstation. Individual images can be rendered at high resolution with a special HD renderer that does not require a lot of memory. It does, however, have to do the full rendering process for each image. When you only need to change the camera view point for an animation or time series, other renderers only need to redo the last rendering step, because they keep the pre-processing information in memory, thereby speeding up the process. Batch processing can, at this time, not be done, e.g. as background processes on servers or supercomputers. This is a project for a future version. Typical modeling applications for astrophysics Morpho-kinematic modeling The original design purpose of Shape was the modeling of the 3-D morphology of nebulae using as additional constraint the kinematics observed in spatially resolved high resolution spectroscopic data. As the structure becomes more and more complex, the traditional approach of direct coding of the volumetric density or emissivity as well as velocity distributions becomes impractical. Therefore the technology of interactive polygon mesh construction as volume containers was adapted to astrophysical needs from conventional 3-D modeling in Computer Graphics. This type of modeling is still the flagship application of Shape. The user builds a 3-D volume distribution of density or emissivity, assigns a velocity field and then produces images, position-velocity diagrams and/or channel maps. This is the main approach for modeling the structure and kinematics of circumstellar gas, be it expanding or rotating, such as in planetary nebulae, supernovae or proto-planetary disks. An extension of this methodology is the application of carbon-monoxide (CO) radiation transfer using the ShapeMol module. This is useful to model high-resolution observations with the ALMA or other radio interferometers. A large number of scientific papers contains models of this type and can be referred to as examples. See the list of publications with Shape and Shape models. Morpho-kinematic Modeling Typical Modeling Applications Photo-realistic Models Beyond scientific application ShapeX can be applied to produce photo-realistic visualizations of a variety of nebulas, stars, galaxies and other types of objects. This type of application often requires a mixture of various modeling techniques, using polygon meshes, particles and hydrodynamics. Since high spatial resolution and substantial model complexity is likely to be required for this type of application, substantially more computing power and processing time might be necessary compared to more basic applications. More detailed information and examples of photo-realistic models, in particular with mixed techniques that include polygon mesh and hydrodynamics can be found in Steffen & Koning (2017) . Photo-realistic Models 3-D Hydrodynamics 3-D hydrodynamics The Hydro Module in Shape allows the simulation of basic astrophysical hydrodynamic phenomena at moderate spatial resolution (depending on the computing power in terms of CPU cores and RAM) solving the basic hydrodynamics equations. A simple radiative cooling scheme is included designed for fast computation above 10000 Kelvin. The details of the numerical scheme have been described in Steffen et al. (2013) . The novel feature of the hydrodynamics in ShapeX is that the user does not require programming the initial conditions. For this task the interactive 3-D polygon modeling interface is applied. The full integration of the hydrodynamic module in ShapeX allows a highly flexible analysis of the simulations and mixture with other modeling techniques. This yields very realistic visualizations for scientific and outreach applications. If you have been using a hydrodynamics code that is not part of Shape and find that your visualization and analysis software does not meet your needs consider Shape for it. You can import data from hydrodynamic simulations and use Shape to generate spectral kinematic output (P-V diagrams, channel maps) and images for any viewing angle. It is also possible complement your model with additional features constructed with Shape´s polygon mesh techniques for scientific modeling or illustration, and much more. Exoplanet transits Exoplanet transit lightcurves The lightcurves of exoplanets are a rich research field for which Shape is very well suited using its animation module for setting up the orbital motion, the rotation of the star with star spots and limb darkening or brightening. Shape can not reconstruct the systems parameters automatically from data, but the user can construct not only the time series of a single transit, but automatically vary a number of parameters and setups that allow the construction of a catalog of transit lightcurves and corresponding videos that shows the transit together with the lightcurve. In addition to the scientific value, the movies can be of use for outreach and press release illustrations. Schematic illustrations Schematic 3-D model illustrations The 3-D polygon mesh models can be used for schematic illustrations of model ideas, even if you are not interested in a physical model. For papers and presentations such models can not only be static illustrations, but as interactive demonstrations or movies they can be powerful tools to convince an audience of one´s ideas. Need a new ShapeX feature? Basic workflow: Interactively add the geometric elements of your object in the form of primitive polygon meshes (Primitives) that you can access at the top menu bar of the 3-D Module. These meshes will serve to encase the volumes that will constitute the different parts of the model. Then you modify the simple structure of the Primitives using what we call Modifiers, which give the objects new geometric structure and physical properties as a function of position in space. Using the Physics Module, you then assign the material and radiation properties to the meshes. Finally, the model is rendered with the Render Module and some of the observational properties can be displayed with the (Channel) Maps and Graph Modules, where the observational data can be included and compared with the model results. If the results are not satisfactory, the model will be adjusted until a satisfactory match is found between observations and model. Need a new Shape feature? Don´t hesitate to contact us , we might be able to help either by finding a solution with the current software or implement a new feature for you, thereby helping other potential users with similar applications. Basic Workflow

Filters for physical quantities in Shape can be defined here. Modules: Hydrodynamics Overview Hydrodynamic simulations are an important area of astrophysics. Shape is the first astrophysical tool to introduce an interactive mesh-based setup for such simulations without the need of programming or scripting by the user. Furthermore the results of the simulations can be directly incorporated in mesh-based renderings without the need of external software. From the hydrodynamics, just like any other mesh model, can be used to generate spectral information. Filtering using the Filter Module allows you to extract regions with particular properties based on the filter settings. Exporting of the hydrodynamic simulation data allows later incorporation of the data or parts of them into a completely different rendering project. The simulations in Shape are always intrinsically 3D on a uniform cartesian grid. The numerical algorithm in Shape was selected to run relatively fast in 3D with a minimum of variables to keep memory usage as low as possible, while still allowing to simulate the basic astrophysical phenomenology such as shocks and radiative cooling above a temperature of 10^4 K, typical to photoionized nebulae. The details of the numerical scheme used for the hydrodynamics, its limitations and example applications are described in the following research article: W. Steffen, N. Koning, et al., 2013, MNRAS, 436, 470–478 It is recommended to use numerical hydrodynamics tools in Shape or any other application only with sufficient understanding of the the possibilities and limitations of such tools. This module in Shape was made to make access to numerical hydrodynamics easier, but if you do not have insight into the potential artifacts the numerical schemes produce, especially at low spatial resolution, it is recommended to seek the assistance of someone who does. General Workflow The workflow involves three overall steps: First, you set up the elements of the simulation in the 3D Module. Second, the flow parameters are set up in the Hydro Module. The simulation is started and previewed here, too. Rendering and analysis is then done as usual in the Render Module vía a dummy rendering object that is set up in the 3D Module. See below for more details on how to set up a simulation in the 3D Module. User Interface The user interface of the Hydro Module consists of three main parts: The visual preview panels, the menu bar at the top and the parameter panel on the right. From the drop-down list at the top of the parameter panel you have access to four sub-panels: General, Flow, Boundaries and Camera. Menu Bar Calculate : The Calculate Button starts a hydrodynamic simulation. Preview : The Preview Button visualizes the initial setup of the simulation in the preview windows, where you can inspect the distribution of density, speed, temperature and pressure. Add : Add a new windows. You can add several new windows to the preview visualization area. This allows you to simultaneously supervise the evolution of different physical quantities or look at them from different viewing angles or filter conditions. Refresh : Refresh all views to the current state of the hydro simulation. Cascade & Tile : Select how to arrange multiple preview windows. They can also me manually arrange by clicking on the top bar and drag them around. Preview Preview : Each of the preview windows gets a new icon on the menu bar. Change the name in the camera parameters panel on the right to suitably represent the content of the window. Save & Load: Save or load the complete state of the hydrodynamic simulation for the current timestep. This allows you to stop the simulation at this time and restart the simulation where you left off after loading the data back with the Open button. The Open button opens the file dialog to select the previously saved file. Loading a file also allows you to use the result in a different project and render it with a different mesh based scene. After loading a data set click the Preview button on the Menu bar to see the simulation preview. How to set up a hydrodynamic simulation in the 3D Module Numbers that you need to start: The physical size of the computational domain in units of meters. Approximate densities (in particles/m^3) of background and active objects Initial velocities in km/s (in the 3D Module), which are then converted automatically to m/s in the Hydro Module and later back to km/s in the Render Module. Filters in the 3D Module require km/s, whereas those in the Hydro Module require m/s. The timescale on which the simulation is likely to finish in seconds (note that 1 year is approximately p x10^7 sec, which easy to remember) . Setup Render Module The first thing to do is to set the Scene Size and Resolution in the Render Module . Scene Size: The physical size from center to edge of the whole computing domain in meters (you may have to choose the correct units in the Units Tab of the Render Module). Resolution: The voxel resolution for the rendering. This does not need to be the same as the hydro simulation resolution with is set in the Hydro Module. Setup 3D Module Hydro Type: Each mesh object in the 3D Module has to be assigned a Hydro Type in the Hydro tab on the right. Background: The computing domain can not have any region that is completely empty. Therefore there has to be exactly one object with the type Background. The mesh of the background object has to enclose the full domain. Best to use a cube object with the size of the domain or larger. The background distribution of physical properties such as density or temperature may or may not be uniform as needed. Initialize: Object that receive all their properties at the beginning of the simulation and change only passively as a consequence of the simulation receive the hydro type Initialize. These could, for instance, be clumps or rings of high density gas. Boundary: Objects that are updated at every timestep or have to remain the same during the simulation are of type Boundary, since they act like a boundary condition. These could be stellar winds or jet that have to inject gas in a controlled, possibly time-variable manner. Variability is controlled in the Animation Module. Modifiers All hydro objects need to have at least one set of modifiers that describe their physical properties. These can either be [Density, Temperature, Velocity] or [Density, Pressure, Velocity] . Density, Temperature and Pressure must not be zero at any position in the domain otherwise the simulation will proceed only for a limited time or crash immediately. The Velocity may of course be zero. Other modifiers may be added as usual to control the shape, orientation and animation of the objects. Any of the modifiers may be animation including those for the physical properties. To some extent Boundary objects can be interactively moved around with the cursor or by changing numerical parameters while the simulation is running . Set up Hydro Module General Tab Grid Size: The number of cells in each direction of the cubic simulation domain. It is the same in all three dimensions. Note that the computational time and memory required for a simulation strongly depend on the Grid Size. While memory increases with the power of three , the required time increases as the fourth power of this grid size, not third power. This is so, because for smaller cells in the same physical domain the time step is also smaller. Therefore to reach the same final time, more time steps are necessary. So, ramp up this number from below, say starting at 64 and monitor memory and computing time as you increase the resolution. The numbers may be any number, no need to be multiples of 2. End time step: The number of time steps to be executed before the simulation is automatically stopped, unless the End Time is reach first. End time: The physical time in seconds after which the simulation shall be stopped automatically, unless the End Time Step is reach first. Resume: If a simulation as stopped or has been loaded from file, enable the Resume flag to continue the simulation. Click the Calculate Button on the Menu Bar to start resuming the computation. Animate: If Boundary Type objects in the 3D module vary in time in their properties, geometry or position/orientation via the Animation Module, then the Animate flag must be on for this time variability to take effect. Pause: Set this flag to temporarily pause the simulation. This can be useful to save the current state to file or generate a rendering of it in the Render Module. To continue the simulation remove the flag. Filters: For visualization purposes various filters can be selected from the drop-down list that select certain regions according to their physical properties. The filters themselves are set in the Filters Module. Note that SI units are used, including m/s for speed (in the 3D and Render Module the speed it in km/s, so different filters are required for the same filter range). You may combine more than one filter. Flow Tab Courant #: The Courant number is a number that controls the stability of the solution of the numerical differential equations of fluid dynamics. This so called CFL condition expresses that the distance that any information travels during the timestep length within the mesh must be lower than the distance between mesh elements. In other words, information from a given cell or mesh element must propagate only to its immediate neighbors. The number should be less than 1, recommended to be less than 0.5, depending on the particular conditions, incl. the strength of the cooling. Note that making the Courant # smaller, also decreases the time step and hence increases the total computing time. Gamma: The adiabatic index of the gas in the equation of state. For monoatomic gas the value is 5/3 (1.66). Eta: The numerical viscosity coefficient. This exchanges some fraction of the conserved physical quantities between neighboring cells and helps to maintain stability. The cost for the stability is diffusion, i.e. for instance high-density regions expand into low-density ones without the need of a pressure gradient. So, the value should be as small as possible, e.g. 1e-4 or smaller. High contrast regions are particularly affected. T0: The minimum temperature in Kelvin to be maintained if cooling becomes too strong within a timestep and would reduce the temperature below zero. For photoionized regions this value may be set to values of order 1e4 K. Otherwise to a reasonable lower value that represents physically plausible low values. Cooling: Enable or disable explicit cooling. See the paper by Steffen et al., (2013) for details. Cooling factor: Apply this factor to the explicit cooling calculation. Boundaries Tab For each side of the cubic domain the boundary condition may be set to Outflow or Reflection . If your simulation is symmetric with respect to a certain plain, then this plane could be one of the boundaries and then a setting of Reflection can be used. Most other applications will have an Outflow condition everywhere. The difference between the two conditions is only how the velocity components of the second to last cell is copied to the last cell. For the Outflow condition the component perpendicular to the boundary is copied as it is, whereas in the Reflection it is inverted. Camera Tab Controls the camera viewpoint and physical variable to be visualized in each preview window. Click on the preview window for which the parameters shall be shown and set. Name: Set the name of the preview window. It is convenient to set it similar to the physical variable to be displayed or some other name that somehow identifies the content. Variable: Select the physical variable to be visualized in the preview window. Note: When you move the cursor over the preview window a value for the physical quantity at the cursor position is shown in the top-left corner of the preview window. This is the integrated value along the line of sight. To see the local value use the Render Slice functionality (see below) to extract a single slice. Then the value shown represents the local value of the variable. Enable: Enable or disable this camera. Ortho: Enable or disable orthographic projection for this camera. Image: Edit the image display parameters for this camera. X Y Z pos: Set the camera position. The X Y positions are currently not functional. When the Ortho mode is disabled, the Z position in terms of the size of the domain (=1) changes the distance of the camera. X Y Z rot: Set the rotation angles of the camera per axis in degrees. The X & Y rotation can also be changed interactively by dragging the mouse over the preview window with the left button pressed. If the resolution of the simulation is small enough for your system, the preview responds interactively at a reasonable framerate. The interactive preview is rendered on the CPU and is therefore efficient only for relatively small resolutions. Render Slice In the Camera Tab you can scroll down to find the Render Slice controls. They allow you to display slices of the full simulation domain to closely inspect particular regions. The slices go along the coordinate axes. The initial position in terms of cell number are set with the sliders labeled X0, Y0, Z0, while the width of the slices are dX, dY, dZ. If you click on the slider handle a number field hopes that allows you to numerically set the value. It is convenient to set the Z width of the slices to 1 and the position to the middle. Then by enabling and disabling the Render Slice with the Enable flag, one can quickly change to a visualization that allows one to read off particular values in the preview window. As mentioned above the local value is only displayed in the preview window, if the width of the slice is set to 1. Otherwise the value shown for the cursor position is the integrated value along the line of sight, where each cell counts with a distance step of 1. For instance, if the integrated value along z is 200 and the domain resolution is 100, then the average local value is 2 along the line of sight at the position of the cursor. Output In the Camera Tab you can scroll down to find the Output section. When enabled it will output the full state of the simulation every dSteps timesteps. Choose a location on the filesystem afer opening the Directory selection dialog by clicking on the folder button. Make sure it is a location with sufficient disk space to accommodate the amount of data that will be saved. Status At the bottom of the Parameters Panel on the right there are three values updated at every timestep of a simulation. They help to judge the current status and rate of progress of the simulation. It show the current total Time in seconds, the current timestep dTime and the number of Step s computed so far. Considering the ratio between the total time and the timestep is very large, then the simulation will be progressing very slowly. This could be a hint to regionally problematic physical values.

Desktop Module Video Tutorial The Desktop Module is your control and navigation center. It allows to open modules and customize the quick navigation bar at the top, open recent projects with a single click, customize general parameters and open utilities. Module area: You can left-click on the icons for the different modules to switch to them. Right-click opens a little button that allows you to pin the icon to the main Menu Bar at the top of the user interface. Alternatively, you left-click and drag the icon onto the Menu Bar. Menu Bar: The Menu Bar is the quick navigation tool and stays there on all Modules. Drag-and-drop icons from the Desktop here and arrange them according to the needs for the most efficient workflow on your project. Right-click on an icon to unpin it from the Menu Bar. Files: In this section of the Desktop you have access to project files. You can save the current project with its current name and location (Save) or save it with a new name or location in the file system (Save As). Furthermore, you can open an exiten project (Open) or clear the current project and start a new one (New). Recent Files: In this section of the Desktop you have access to project files that you have been working on recently using a quick access button. Just click on the button of the project that you would like to open. If the displayed file name is not enough to identify the correct project, just hover over the button to display the full file path as a tool tip. Information tools: There are a few tools that will display useful information or where you can configure a few general parameters that you might need to change from their defaults in order to optimize the performance of ShapeX on a particular system. The Memory tool will show the memory usage as a function of running time. The Progress tool shows how the difference forground and background processes are progressing. The Help tool opens this website. The Config uration tool allows you to set multi-threading and autosave parameters (how often the current project file is backed up automatically), as well as a project directory, where ShapeX will start to look whenever you open a file dialog. System information about the interactive Java3D libraries and other Java system data can be found in the J3D and System information tools. Commands: There a few additional tools that are either just commands to be executed or open a tool that did not fit into the other categories. The Shape It! button simply executes a rendering and is equivalent to the Render button located at the left end of the Menu Bar. The Reset button resets the Menu Bar to its default configuration with the minimum necessary modules. Finally, the Units tool open a utility that allows to convert between different units, such as cgs to SI, which come in handy since many astrophysics books use cgs units, while ShapeX works with SI units.

They are a key functionality in ShapeX the usage of which should be mastered in order to create the most realistic models. Modifiers determine the properties of the objects as a function of position in space, hence it is important to know as much as possible about coordinate systems in general (Spherical, Cartesian & Cylindrical) and how they are used in ShapeX. See Coordinate Systems for more information on this topic. Modifiers are assigned to an object in the form of a list or Modifier Stack . This list of operators is executed on the object from the top to the bottom. For many of the modifiers the order in which they are executed does not matter. However, some operators, e.g. those that globally or locally involve some form of rotation, need to be stacked in the right order to produce the desired result. It is therefore important to know whether they order can be reversed or not. Knowledge about commutative properties of operators, or sufficient experimentation, is useful here. Modifiers Overview Modifiers are a operators in the 3-D module that allow you to add or change, i.e. modify properties of an object in the scene. There are different types of modifiers, some change the geometry of the mesh objects, others assign scalar or vector type physical properties such as density or velocity, respectively. After adding or selecting a particular modifiers, its Properties are displayed under the Modifier Stack . These can then be edited either by changing parameter value fields or after opening additional dialogs or graphs. Adding or deleting modifiers is done using the blue + and the red x sign, respectively. When you select a modifier you can move it up and down in the stack with the green arrows. More than one modifier of the same type can be applied with different coordinate systems. In some cases you might have to change the Operation setting from Replace to either Add or Scale , otherwise the last modifier of this type replaces all previous ones. Using combinations of the same type of modifiers allows a larger variety of structures to be build. Modifiers can also be copied and pasted with the corresponding buttons. When you use the paste button, a small dialog will open that asks you to decide whether the modifier should be a copy or and instance of the original modifier. When you choose copy then the new modifier will be completely independent from the other. However, and instanced modifier will always change together with its original and vice versa. Instanced modifiers are a great tool to provide the same parameters for more than one object, while only needing to change a single one of them. Types of Modifiers Physical Modifiers Physical modifiers add or change physical properties as a function of position. They include the Density , Temperature , Pressure , Image Texture , Taper , Velocity, GField and BField . The Boost modifier is a helper modifier to the scalar physical modifiers and is used to change those quantities, but depending on the geometry of another mesh object. This is useful, for instance, to reduce or cut out part of the density of one object using another. Geometry Modifiers Geometry modifiers change the structure of the polygon mesh. They include Bump, Curvature, Displacement, Image Displacement , Projection, Random, Sculpt, Shear, Shell, Size, Spiral, Squeeze, Squish, Stretch, Texture Displacement, Twist, Universal, and Warp . The geometry modifiers move the vertices of a polygon mesh within the local coordinate system of an object. If you move or rotate the local coordinate system with a Rotation or Translate modifier, then the geometry modifiers act in the transformed coordinate system. Note that the Displacement modifier is a geometry modifier and moves only the vertices, but not the origin of the local coordinate system is does the Translate modifier. This is useful when you want to move a complete object, such as a small sphere within a fixed coordinate system and apply, for instance, the Velocity or Density modifiers in the original coordinate system. Modifier Parameter Panel: Common Parameters The parameters that modifiers take vary considerably. They are described in the sections for individual modifiers. What they have in common are the Name field and the Enabled flag . In the Name field you can set a name for this particular modifier, which is strongly recommended, since it allows one to easily identify a modifier, which becomes more and more important once the number of modifiers increases for a particular object or for the project itself. It is especially important once the Modifier Module is used to manage a large number of modifiers. As the name implies, the Enabled flag allows one to enable or disable a particular modifier. Modifier Module: The Modifier Module becomes important once a model contains a large number of objects and modifiers. Often different objects have similar basically the same modifiers that have at least some parameters in common. If they are not instances of each other or have their parameters organized as global variables, the Modifier Module allows you to select a number of modifiers and change their parameters in a single operation. It also provides a good way to get an overview of which modifiers are used by which objects as well as the possibility to sort them by type. For more details on the Modifier Module go to its more detailed description in its own section of this manual.

Filters for physical quantities in Shape can be defined here. Filter Module Overview A variety of box filters can be defined in this module and applied to objects in the 3-D Module. To apply the filter look for the Filters drop-down list in the General Parameters tab for mesh objects. All filters defined in the Filters Module appear in this drop-down list. Select the filters to be applied. The Filter Module has three main areas, the Tool Bar at the top, the Filter List on the left and on the right the Options for the selected filter. Menu Bar: Add: Use the Add button to add a new filter to the Filters list. When you click on this button a pop-up opens with a list of Filter Types from which to choose one. In the Options Panel change the Name to something recognizable, e.g. the name of the object to which it will be assigned or something that describes the function it is meant to do. Remove: Remove the selected filter from the Filters list. Make sure you have selected the the filter that you really mean to delete. Copy: Copy the selected filter within the Filters list. Best to rename the filter to make it uniquely recognizable. Change the parameters in the Options Panel. Sort: Sort the filters alphabetically in the Filters list. Open: Load a previously saved filter from disk. A file opening dialog will open for you to select a file. Save: The selected filter will be saved to disk. A file saving dialog opens. Select the directory and filter name to be saved. Add an extension that helps you to recognize the file as a Shape-Filter. While you can choose any extension, we recommend to use .shf. Options: Name: Set a descriptive name for the filter. This name appears in the Filter selection drop-down list in objects in the 3-D Module. Enable: The check box activates or disactivates this filter for all objects that use it. Mode: Here to can chose the Mode of the filter, which refers to whether the range between the Min and Max values is to be included or excluded. Clamp: If checked then all values above the Max values are set to the Max values. If unchecked, then the value is set to zero. Min & Max: The minimum and maximum of the filter range.

Export Module Overview The Export Module exports the 3-D model into various output formats that can then be used as data for external use. It was mainly designed to prepare models for export to the iluvia software for external interactive visualization. The Export Module uses data from an intermediate output of Shape that contains all the radiation information within a cubic grid with uniform voxels. The name and disk folder in which this intermediate file is located are set in the Output tab of the Render Module . Exporting Shape models into new formats for external visualization may be a challenge. This is due to the fact that in Shape you may can use a variety of physical radiation effects, some of which can not be directly mapped to the simpler treatment of emission and opacity in interactive graphics software that rely on ARGB color coding or similar. General Workflow: In the Output tab of the Render Module, make sure there is a valid filename and path provided. The output will be with the extension .ilv . This file is loaded into the Export Module. Then a previsualization is generated by adjusting the parameters on the left and right side of the preview image in the middle. The parameters on the left adjust the behavior on the level of the voxels of the input grid. Those on the left adjust the visualization on the image plane after the preview rendering. The preview attempts to recreate the view of a GPU rendering by simulating a similar shader. It also allows you relatively quick interactive inspection. For low resolution you can interactive rotate the object for inspection. Parameter Panels: Volume: The parameters on the left side of the preview control the values of voxel data cube before it is previewed and converted to a different data format. Note that scaling and clamping these values in the presence of opacity maybe result in non-linear behavior that sometimes is not intuitiv. In combination with the parameters on the output side (Preview parameters), it may require some trial and error to obtain the expected result. Filename: Select the .ilv input file to be used for exporting to an external file format. Click on the icon on to the right of the text box to open the file system dialog and choose a file from disk. Reload: If the content of the input file has been updated and the filename remains the same, use the Reload Button to load the new content. Size: Shows the width of the cube by the number of voxels along one side. Downsample: If the original .ilv file is too large, it can be downsampled x2 in terms of side length by clicking on this button. Intensity range: The range of voxel intensities. Histogram: The histogram of the voxel intensity values opens when this button is clicked. Opacity range: The range of opacity values is shown. Histogram: Shows the histogram of the voxel opacity values when this button is clicked. Intensity scale: Scale all voxel intensities by this factor. Opacity scale: Scale all voxel opacity values by this factor. Max Intensity: Set the value of the maximum intensity. All higher values of voxel intensity are clamped to this value. If the default value of -1 is set, then the maximum value of all voxels is automatically used. Max Opacity: Set the value of the maximum opacity. All higher values of voxel opacity are clamped to this value. If the default value of -1 is set, then the maximum value of all voxels is automatically used.} Show stars: This flag switches on any stars that might be saved in a file that has the same base name as the .ilv file. Show volume: Shows the volume save in the .ilv file. Show cube: Show a line cube that delineates the space domain of the .ilv file. Preview: The Preview parameters to the right side of the preview image window control the preview in the output format. It allows you relatively quick interactive inspection. For low resolution you can interactive rotate the object for inspection. Image size: The preview image resolution in pixels. Lower resolution allows for a faster and more interactive preview. I factor: Intensity factor to be applied to the preview at the image level. Star factor: A scaling factor for the brightness of the stars. A factor: A scaling factor for the opacity. Camera: X, Y, Z rot: The rotation angles of the preview camera around the cartesian coordinate axes (in degrees). X, Y, Z pos: The shifted position of the preview camera around the cartesian coordinate axes in units of the width of the domain (0-1). Zoom: Camera distance from the center in units of the width of the domain. Reset Camera: Set the camera values back to the defaults. Statistics: Shows the Maximum value of the preview image. It is convenient to adjust this to values near 1. Export: Format: Various output formats can be chosen. Most importantly, the DDS format is a standard format that encapsulates slices of the data cube in ABGR image format, that can then be imported in external volume visualization software. This is also the format for the iluvia software that is developed by ilumbra.com where you can fully interactively view your models. The Volume option, is a .ilv file with properties that correspond to the transformation that the Export Module made to the original. The PNG option outputs a sequence of slices of the volume in standard PNG image format including absorption. The slices are in the XY plane and change along the Z-axis of the World Coordinate System. Directory: Select the directory on disk where to output the exported file. Omit empty: When selected, the slices where the emission and opacity are both zero will be omitted from the output. This may save data and may reduce the load on the visualization system that will process the output data. Crop: . When activated, the output will be cropped to a size of Crop size. This is useful for models in which for some reason the domain is significantly larger than the content. Export: Start the export process.

Coordinate Systems The hierarchy and types of coordinate systems is key to the flexibility of the modeling of structures and velocity fields. Video Tutorial The Modifier Stack Graphical representations of functions are a fundamental tool to control parameters that vary in space, time or wavelength. Video Tutorial Graphs Graphical representations of functions are a fundamental tool to control parameters that vary in space, time or wavelength. Video Tutorial Textures Textures are either random procedural 3-D structures or external images that determine structures of density, temperature or others. Video Tutorial Particles Particles are used to generate complex specific structures by spraying them interactively on surfaces and into volumes. Video Tutorial