```
``` v3d_help
SYNOPSIS
List a summary of the v3d routines
USAGE
v3d_help;
DESCRIPTION
List a summary of the v3d routines
NOTES
SEE ALSO
v3d_setup
--------------------------------------------------------------
v3d_list
SYNOPSIS
List the current values of v3d cube radius and resolution
USAGE
v3d_list;
DESCRIPTION
List the values of v3d_cube_radius, v3d_user_unit and
the resolution, v3d_na, the number of cells per radius.
NOTES
SEE ALSO
v3d_setup
--------------------------------------------------------------
v3d_setup
SYNOPSIS
Initialize the v3d size and resolution values
USAGE
v3d_setup (cube_radius, n_cells_per_radius);
DESCRIPTION
The variables v3d_cube_radius and v3d_na are set and used
by other v3d routines.
Also, the variable v3d_va is filled with the 2N+1 values
of the centers of the cells along the (symmetric) axes.
NOTES
The variable v3d_user_unit is available to store a desired
string describing the units of v3d_cube_radius, but it is not
required to be used.
SEE ALSO
v3d_list
--------------------------------------------------------------
v3d_soft_cutoff
SYNOPSIS
Provides a continuous (smoothed) step function
USAGE
where_negative = soft_cutoff (values - threshold);
DESCRIPTION
A function that returns:
1.0 for values << 0
0.0 for values >> 0
and transitions from 1.0 to 0.0 in the
range of values -5 to +5 with
-0.5 to 0.5 going from 0.7 to 0.3 ish
-1 to +1 going from 90% to 0.1 roughly
and
-2 to +2 going from 99% to <0.01
Use v3d_soft_cutoff() to define slightly smooth edges:
... v3d_soft_cutoff( (location-boundary) /
(v3d_cube_radius/(2.0*v3d_na)) )
NOTES
Can see the details of this function
by showing how much it differs from 0 or +1 :
v3d_setup(10.0,37);
plot(v3d_va, 0.5 - abs( v3d_soft_cutoff(v3d_va) - 0.5) );
SEE ALSO
--------------------------------------------------------------
v3d_merge_max
SYNOPSIS
Combine two 3D arrays by taking the cell-by-cell maximum
USAGE
arr3d_max = v3d_merge_max (arr3d_a, arr3d_b);
DESCRIPTION
Combines two 3D arrays by returning an array containing the
cell-by-cell maximum values. This is useful to produce the
union of two geomtric shapes.
NOTES
SEE ALSO
--------------------------------------------------------------
v3d_smooth_box
SYNOPSIS
Do box-car smoothing of a 1D array
USAGE
smarr1d = v3d_smooth_box (arr1d, nsmooth);
DESCRIPTION
Returns a smoothed version of the 1d array
smoothing is in integer units nsmooth = (1,) 2, 3,...
- for odd integers the average of nsmooth values is used
- for even integers, the next largest odd value is used
and the two extreme bins are weighted by 1/2.
NOTES
The ISIS routine "rebin" does a similar (better)
thing when the output bin scheme is well defined.
SEE ALSO
v3d_smooth_2d, v3d_2dto3d
--------------------------------------------------------------
v3d_smooth_2d
SYNOPSIS
Box-car smooth a 2D array
USAGE
smarr2d = v3d_smooth_2d (arr2d, nsmooth);
DESCRIPTION
Simple box-car smoothing in 2D.
NOTES
Used by the simple v3d_evtimg routine.
SEE ALSO
v3d_smooth_box
--------------------------------------------------------------
v3d_r3dsq
SYNOPSIS
Returns a 3d array with r-squared in each cell
USAGE
v3darr = v3d_r3dsq (oxyz=[x,y,z]);
DESCRIPTION
Given a center location, oxyz=[x,y,z], this
returns a v3d array filled with each cell's
distance squared, r3dsq, from the center location.
NOTES
SEE ALSO
--------------------------------------------------------------
v3d_cube
SYNOPSIS
Fill a v3darr with 1.0 within a cube
USAGE
v3darr = v3d_cube (radii [,oxyz]);
DESCRIPTION
Fill a 3d array with values of 1.0 inside a cube
of radius radii centered at OXYZ.
Radius can be a single value (the same for all axes)
or an array of 3 values, one for each axis:
radii = radius or [radx, rady, radz]
NOTES
Note that this cube is always aligned with the axes
and hence takes no optional rthphi parameter.
SEE ALSO
--------------------------------------------------------------
v3d_cone
SYNOPSIS
Fill a v3darr with 1.0 within a cone
USAGE
v3darr = v3d_cone (angin, angout, axmin, axmax [,oxyz [, rthphi]]);
DESCRIPTION
Creates a cone based on the parameters:
angin, angout: opening half-angles of inner and outer boundaries
in degrees
axmin, axmax: axial limits (w.r.t. center) of the emission
Centered (vertex) at OXYZ
The axis of the cone is given by:
rthphi = [theta, phi] where:
theta, phi are the polar coordinates of the axis:
theta is angle in degrees from X toward -Z axis.
phi is angle in +/- degrees from X-Z plane toward +/- Y axis
Default is Axis along +Y.
NOTES
SEE ALSO
--------------------------------------------------------------
v3d_cylinder
SYNOPSIS
Fill a v3darr with 1.0 within a cylinder
USAGE
v3darr = v3d_cylinder (rin, rout, axmin, axmax [,oxyz [, rthphi]]);
DESCRIPTION
Creates a cylinder using the parameters:
rin, rout: radii of inner and outer boundaries
axmin, axmax: axial limits (w.r.t. center) of the emission
Centered at OXYZ
Axis of the cylinder is given by:
rthphi = [theta, phi] where:
theta, phi are the polar coordinates of the axis:
theta is angle in degrees from X toward -Z axis.
phi is angle in +/- degrees from X-Z plane toward +/- Y axis
Default is Axis along +Z.
NOTES
SEE ALSO
v3d_cyl_azlup
--------------------------------------------------------------
v3d_cyl_azlup
SYNOPSIS
Fill a cylinder using an azimuth look table
USAGE
v3darr = v3d_cyl_azlup (rin, rout, axmin, axmax, oxyz, rthphi, azlups [, vlups]);
DESCRIPTION
Create a cylinder with aximuthal lookup values or limits.
rin, rout: radii of inner and outer boundaries
axmin, axmax: axial limits (w.r.t. center) of the emission
Centered at OXYZ
Axis of the cylinder is given by:
rthphi = [theta, phi] where:
theta, phi are the polar coordinates of the axis:
theta is angle in degrees from X toward -Z axis.
phi is angle in +/- degrees from X-Z plane toward +/- Y axis
Default is Axis along +Z.
The arguments azlups and vlups give the azimuth (in degrees,
from -180 to 180) and scalar values look-up arrays used
to assign values vs azimuth.
If vlups is not present then the first and last elements of
azlups are used to define the azimuthal range in which the
cylinder has value 1.0 and 0.0 otherwise.
NOTES
Uses the gsl interp_linear function to do the lookup of vlups.
If interp_linear is not available then the routine will still
compile but functions as if vlups is not provided.
SEE ALSO
--------------------------------------------------------------
v3d_list
SYNOPSIS
Fill a v3darr with 1.0 within a Roche lobe
USAGE
v3darr = v3d_roche (r_sep, q_ratio [, thresh_adj, [,oxyz [, rthphi]]]);
DESCRIPTION
Creates a roche lobe filled with 1.0 inside.
The gravitational potential is used
to determine the boundary of the lobe.
Parameters are:
r_sep = separation between objects
q_ratio = m_lobe_object / M_companion
thresh_adj gives the percentage increase in potential applied to set
the roche volume. A value of 2 gives a nice looking shape;
a value of 0 or minus-a-few might better represent where wind
(higher KE, loosely bound) material may be flowing in the system...
Centered at OXYZ
Direction to companion is given by:
rthphi = [theta, phi] where:
theta, phi are the polar coordinates of the axis:
theta is angle in degrees from X toward -Z axis.
phi is angle in +/- degrees from X-Z plane toward +/- Y axis
Default is Axis along -X.
NOTES
SEE ALSO
--------------------------------------------------------------
v3d_sphere
SYNOPSIS
Fill a v3darray with 1.0 inside a spherical shell
USAGE
v3darr = v3d_sphere (rin, rout [,oxyz ]);
DESCRIPTION
Creates a 3D datacube describing a sphere
with radii rin and rout, centered at oxyz=[x,y,z]
NOTES
SEE ALSO
v3d_sphere_rlup
--------------------------------------------------------------
v3d_sphere_rlup
SYNOPSIS
Fill a v3darr within a spherical shell from lookup vs r.
USAGE
v3darr = v3d_sphere_rlup (rin, rout, rlups, vlups [,oxyz ]);
DESCRIPTION
Creates a spherical shell with values as a function of radius as
given by a lookup table. The parameters are:
rlups and vlups are 1d arrays of radii and values
When the lookup tables are on a much finer scale than the v3d resolution
it is useful to use v3d_smooth_box to average the vlups array to the
appropriate scale.
NOTES
Uses the gsl routine interp_linear to do the lookup and is not
compiled unless inter_linear is present.
SEE ALSO
--------------------------------------------------------------
v3d_sphere_line
SYNOPSIS
Fill a v3darr with a line of spheres
USAGE
v3darr = v3d_sphere_line (p1xyz, p2xyz [, rout [, nspheres]]);
DESCRIPTION
A line of nspheres is produced in the v3darr. The first and
last sphere are centered at the points p1xyz and p2xyz,
specified as a simple array: pNxyz = [px,py,pz] .
NOTES
SEE ALSO
v3d_sphere_ring
--------------------------------------------------------------
v3d_sphere_ring
SYNOPSIS
Fill a v3darr with a ring of spheres
USAGE
v3darr = v3d_sphere_ring (r_ring, r_sph, nspheres [,oxyz [, rthphi]]);
DESCRIPTION
A ring of nspheres is produced in the v3darr.
The circualr ring has center at oxyz and normal
in the direction rthphi.
NOTES
SEE ALSO
v3d_sphere_line
--------------------------------------------------------------
v3d_torus
SYNOPSIS
Fill a v3darr with 1.0 within a torus
USAGE
v3darr = v3d_torus (rin, rout [,oxyz [, rthphi]]);
DESCRIPTION
Creates a torus in the v3darr based on the parameters:
rin and rout are the inner and outer radii of the solid
torus in its equatorial plane.
Centered at OXYZ
Axis of the torus is given by:
rthphi = [theta, phi] where:
theta, phi are the polar coordinates of the axis:
theta is angle in degrees from X toward -Z axis.
phi is angle in +/- degrees from X-Z plane toward +/- Y axis
Default is Axis along +Z.
NOTES
SEE ALSO
--------------------------------------------------------------
v3d_list
SYNOPSIS
Fill a spherical shell with values from a 2D array
USAGE
v3darr = v3d_2dto3d (arr2din, rlo, rhi [,oxyz [, rthphi]]);
DESCRIPTION
Fill a spherical shell with values based on a 2D array
which gives the values in a grid of lattitude-radii:
arr2din [ ilattitude_0_to_90, iradius_rlo_rhi ]
Assumes the lattitude is complete from 0 to 90 degrees
and is reflected for negative lattitudes.
The user provides rlo and rhi to set the radius scale.
Centered at OXYZ
Axis of the object (lattitude = 90 degrees) is given by:
rthphi = [theta, phi] where:
theta, phi are the polar coordinates of the axis:
theta is angle in degrees from X toward -Z axis.
phi is angle in +/- degrees from X-Z plane toward +/- Y axis
Default is Axis along +Y.
NOTES
SEE ALSO
--------------------------------------------------------------
v3d_f_generic
SYNOPSIS
Calculate a general function of coordinates
USAGE
v3darr = v3d_f_generic ("dummy_f_string" [,oxyz [, rthphi]]);
DESCRIPTION
Evaluate a user-provided function of Cartesian, cylinderical, and/or
spherical coordinates.
Available variables in the rotated system are:
(all of these are arrays along the ix cube dimension)
Cartesian:
axial [=xprime], yprime, zprime
spherical:
rad3d and rad3dsq[uared], lattitude, azimuth
cylindrical
radcyl, axial, azimuth
At present the supplied string is a dummy argumment and the user
must use this routine as a template and modify the line:
val[*,iy,iz] = ... ;
to compute the desired function of the coordinates.
The computation of unneeded variables can be commented out or removed
as well to speed evaluation.
The coordinates are centered at OXYZ
The axis of the object is given by:
rthphi = [theta, phi] where:
theta, phi are the polar coordinates of the axis:
theta is angle in degrees from X toward -Z axis.
phi is angle in +/- degrees from X-Z plane toward +/- Y axis
Default is Axis along +Y.
NOTES
The goal was to be able to define the general function by passing
in a function string or a reference to a user-created function:
f_string = "(cos(3.0*azimuth))^2 * (sin(5.0*lattitude))^2 *" +
or "exp(-1.0*rad3dsq/(40.0)^2)";
f_string = &f_to_use
and the routine would determine which type of f_string is given.
This may be a bit tricky to do... Hence the suggestion to use this as
a template.
SEE ALSO
--------------------------------------------------------------
v3d_view
SYNOPSIS
Display a 3D volume with the volview guilet
USAGE
v3d_view (v3darr [, file_name_h5]);
DESCRIPTION
The 3D volume array is conditioned and passed to volview for display.
Specifically the "correct" xyz orientation is achieved:
+X is to the right,
+Y is "up" and
+Z is toward the observer.
Negative values are clipped to 0.0 . This allows a simple thresholding
view of the volume:
v3d_view ( v3darr - threshold_value );
Also, a sqrt() function is applied to reduce the dynamic range of
the array.
A useful way to save and share the viewed 3D model
is through the optional filename: if present then the array passed to
volview is written to the filename by h[df]5_write.
This file can then be re-viewed with the command:
volview(h5_read(file_name_h5));
NOTES
This routine is only compiled if volview is available.
The ability to write h5 files requires h5_write - but the routine
will compile with out it.
SEE ALSO
v3d_project
--------------------------------------------------------------
v3d_project
SYNOPSIS
Show a projected [color-coded] image of the 3D array(s)
USAGE
v3d_project ( [rarr], [garr], [barr]);
DESCRIPTION
This routine shows a "thin" projection of a v3d volume
as seen from the nominal viewing location:
the observer is at a large +Z location looking along -Z.
The resulting image has +X to the right and +Y "up".
A single v3d array can be passed in for monochrome display,
or two or three v3d arrays for RGB colors.
Array values that are negative are clipped to 0.0 .
NOTES
This routine requires imdisplay from slgtk.
The nominal data sent to imdisplay is a 3d array
of the form UChar_Type[nypix,nxpix,3] where the
three "planes" are R,G,B and values are from 0 to 255.
SEE ALSO
v3d_view
--------------------------------------------------------------
v3d_evtimg
SYNOPSIS
Bin and display a set of events with color coding
USAGE
v3d_evtimg (xs, ys [, es [, Rrange, Grange, Brange]]);
DESCRIPTION
The arrays of points xs,ys are binned in 2D and the histogram
is displayed. If the optional es array (e.g., "energy") is
provided, then the R-G-B-ranges are used to assign events to
R-G-B image planes for color coding, e.g.,
Rrange = [rmin,rmax] selects the es for the R plane
A small amount of smoothing is applied to the image planes to
reduce graininess in the image.
NOTES
This routine requires imdisplay from slgtk and also
hist2d from the histogram module.
This is a very-lite version of the evt2img.sl tool which
displays fits files with interactive RGB selection, etc.
SEE ALSO
v3d_mc_points, v3d_doppler_points
--------------------------------------------------------------
urand
SYNOPSIS
Generate uniform random numbers from 0.0 to 1.0
USAGE
rand_values = urand (n_samples);
DESCRIPTION
Returns n_samples from a uniform random distribution between
0.0 and 1.0.
NOTES
urand() is the random generator available in ISIS and used here if
it is available (along with seed_random().)
If it is not available from ISIS then it and seed_random() are created
from the gsl ran_flat, rng_set, and rng_alloc routines if gsl is available.
SEE ALSO
--------------------------------------------------------------
v3d__mc_cells
SYNOPSIS
Generate Monte-Carlo random cells from a v3d array
USAGE
(ixs, iys, izs) = v3d_mc_cells (v3darr, nevts);
DESCRIPTION
Selects nevts number of random cells from the v3d array
and returns arrays of their indices: ix, iy, iz .
The probability of a cell being selected is proportional
to the cell's scalar value in the v3d array.
The v3darr is assumed to be non-negative.
NOTES
Requires the urand routine.
SEE ALSO
v3d_mc_points, urand
--------------------------------------------------------------
v3d_mc_points
SYNOPSIS
Generate Monte-Carlo random points from a v3d array
USAGE
(xs, ys, zs) = v3d_mc_points (v3darr, nevts);
DESCRIPTION
Generate nevts number of Monte-Carlo x,y,z points with the
probability of the point proportional to the local value
of the v3darr cell.
The points are uniformly spread within the cells.
The v3darr is assumed to be non-negative.
NOTES
Requires the urand routine.
( Note that optional rotations could be added to allow "viewing" the
object at some other angle besides the nominal (observer located at large +Z),
but not implemented for the moment and for overall modeling simplicity of having
a pre-defined viewing direction. )
SEE ALSO
v3d_mc_cells, urand
--------------------------------------------------------------
v3d_doppler_points
SYNOPSIS
Calculate the Doppler energy correction given velocity properties
USAGE
en_factor = v3d_doppler_points (x,y,z, vsxyz [, velval [, vtype [, oxyz [, rthphi]]]]);
DESCRIPTION
This routine takes in values of x,y,z of events
and returns values of en_factor where en_factor is the energy
Doppler factor based on the line-of-sight velocity of
the points.
The velocity at x,y,z, is a sum of terms:
- systemic velocity: vx, vy, vz [km/s]
- radial or rigid-body rotation:
velval, vtype, oxyz, rthphi
with vtype specifying the velocity properties:
0 v = velval [km/s] * r_hat with center at oxyz
1 v = velval [km/s per unit] * r_vector, center at oxyz
2 v = rigid body rotation:
|v| = velval [km/s per unit] * r_cylinder
with rotation axis through oxyz in direction rthphi.
3 v = Keplerian: v_hat as in 2 but |v| ~ 1/sqrt(r)
and for vtype = 1 or 2: set velval = v(ro)/ro
= 3: set velval = v(ro)*sqrt(ro)
NOTES
The special relativistic ENERGY correction factor is given by:
en = lambda_0/lambda_los = 1/ (1+red_shift) =
= 1 / ( gamma * (1 + beta cos(alpha)) )
gamma = 1/sqrt(1-beta^2)
beta = v/c
beta cos(alpha) = v dot los_hat / c
SEE ALSO
v3d_mc_points
--------------------------------------------------------------