RAWTOMINC(1)

💅 rawtominc — straight outta the MINC User's Guide ✨

🌸 NAME 🌸

rawtominc — bestie, this thing converts a stream of binary image data into a minc format file. that's it. that's the job. 💖

---

🦋 SYNOPSIS 🦋

rawtominc [options] output.mnc [[sz4] sz3] sz2 sz1

---

✨ DESCRIPTION ✨

okay so here's the tea ☕ — rawtominc reads a stream of binary data from standard input and writes it into the minc format file output.mnc. and when I say binary data I mean it: byte, short, long, float or double. unless you use the -input option, in which case it reads from a file like a normal person. 🫶

you specify the dimension sizes going from slowest varying to fastest varying. at least two dimensions must be given (that's an image, bestie, you need at least that) but you can go up to four. 🎀

and the options?? the options let you control dimension names, data types, and voxel-to-world coordinate conversion. vector type data (like RGB pixel data, hello 👑) can be read in too. iconic.

---

🌈 PIXEL VALUE SPECIFICATION 🌈

so pixel values are specified by a type and a sign (e.g. signed short integer). they're also characterized by a range of legal values. for example, lots of scanners produce images stored with short integer pixel values. some have values in the range 0 to 4095, others 0 to 32000, others -32768 to 32767. that range is the valid range, and you specify it with the -range option. (for floating point values, the valid range is the maximum and minimum of the whole dataset — no cap.)

rawtominc lets you specify both the input type, sign and range and the output type, sign and range. read short values, store byte values, whatever. slay. 💅

there's a further twist though, and it's giving plot twist 😭:

• Integer pixel values are generally taken to be simply scaled pixel representations of real (meaningful) physical values.
• Floating point values are taken to be the real value itself.

so floating point values get scanned for the maximum and minimum, since they could be anything — and they're stored in the MINC variables image-max and image-min. integer values, however, are not scanned by default, since their range can be given by an option. but if you need to force scanning of integer values when the max and min are not known (some scanners produce files with variable ranges), use the option -scan_range. periodt. ✨

---

🧚 WORLD COORDINATES 🧚

world coordinates refer to millimetric coordinates relative to some physical origin (either the scanner or some anatomical structure). voxel coordinates are simply the indices into the image volume of a given voxel. and ngl, it's worth describing briefly how MINC coordinate conversions work, because this will affect how successful your new MINC file will be. no pressure bestie 💀

each dimension of a MINC image is specified by name — the spatial dimensions are xspace, yspace and zspace. the convention is:

• positive xspace coordinates run from the patient's left side to right side
• positive yspace coordinates run from patient posterior to anterior
• positive zspace coordinates run from inferior to superior

for each of these spatial dimensions, the world coordinate conversion is specified by a pair of attributes: step and start. the xspace world coordinate, for example, is calculated using x = v*step + start, where x is the x world coordinate and v is the voxel count (starting at zero). so:

• the magnitude of the step attribute specifies the distance between voxels
• the sign of the step attribute specifies the orientation of the axis

programs will use this information to display images with the correct aspect ratio and orientation, so make sure you get it right. 🙈

lots of scanners store transverse images with the first pixel at the patient's anterior/right side, so you'd need to give negative x and y step values. other conventions have the opposite: first pixel at patient's posterior/left, so step values are positive. sometimes the first slice is inferior, so the z step should be positive. other times it's superior, so z step is negative. iykyk 🌸

and here's the part that's lowkey mind-blowing: the image axes do not have to be aligned with the world coordinate axes. the axis directions are recorded in the file as direction cosines — unit vectors — one for each spatial axis. in this case, the step and start attributes described in the previous paragraph refer to distances along the axis, not to coordinates of the first voxel. this makes them invariant under a change of axis direction (the whole coordinate system can in fact be rotated just by changing the direction cosines, bestie, that's the power ✨). if the coordinate of the first voxel is known, then it can be converted (projected) to a set of start values by using the -origin option. 🎀

---

👑 OPTIONS 👑

💫 Dimension ordering

• -transverse — Transverse images: [[time] z] y x (this is the default, bestie)
• -sagittal — Sagittal images: [[time] x] z y
• -coronal — Coronal images: [[time] y] z x
• -time — Time ordered images: [[z] time] y x
• -xyz — Dimension order: [[time] x] y z
• -xzy — Dimension order: [[time] x] z y
• -yxz — Dimension order: [[time] y] x z
• -yzx — Dimension order: [[time] y] z x
• -zxy — Dimension order: [[time] z] x y
• -zyx — Dimension order: [[time] z] y x
• -dimorder dim1,dim2[,dim3[,dim4]] — specify an arbitrary dimension order, given by a comma-separated list of between 2 and 4 dimension names. go off, customize your order 💅
• -vector size — gives the size of a vector dimension (which is always the fastest varying dimension, no exceptions). default is no vector dimension.

---

🍓 Input data type and range

• -byte — 8-bit integer values (default).
• -short — 16-bit integer values.
• -int — 32-bit integer values.
• -long — superseded by -int. (rip, it's giving legacy 💀)
• -float — single-precision floating point values.
• -double — double-precision floating point values.
• -signed — values are signed integers (default for short and long). ignored for floating point types.
• -unsigned — values are unsigned integers (default for byte). ignored for floating point types.
• -range min max — specifies the valid range of pixel values. default is the full range for the type and sign. this option is ignored for floating point values.
• -real_range min max — specifies the real range of image values that corresponds to the pixel values of option -range. default is to not store the real image minimum and maximum. if -scan_range is used, then the image minimum and maximum corresponding to the scanned pixel minimum and maximum are calculated and stored. this option is ignored for floating point values.
• -swap_bytes — input values (either -short or -int) need to be converted between Motorola (big-endian) and Intel (little-endian) data format. if short input is specified, adjacent bytes are swapped. if int input is specified, inner and outer byte pairs are swapped. this option has no effect with other input types.

---

🦄 Output data type and range

• -obyte — store 8-bit integer values (default is input type).
• -oshort — store 16-bit integer values (default is input type).
• -oint — store 32-bit integer values (default is input type).
• -olong — superseded by -oint.
• -ofloat — single-precision floating point values (default is input type).
• -odouble — double-precision floating point values (default is input type).
• -osigned — values are signed integers (default for short and long). ignored for floating point types. if output type is not specified, then default is input sign type.
• -ounsigned — values are unsigned integers (default for byte). ignored for floating point types. if output type is not specified, then default is input sign type.
• -orange min max — specifies the valid range of pixel values. default is the full range for the type and sign. this option is ignored for floating point values. if output type and sign are not specified, then the default is the input range.

---

🔥 Scanning integers for range

• -noscan_range — do not scan integer values for their minimum and maximum — assume that the -range option gives the appropriate range of pixel values (this is the default). no rescaling of pixel values is done (unless the output type differs from the input type) and the created images are assumed to have a real (not pixel value) minimum and maximum of zero and one.
• -scan_range — integer values are scanned for their minimum and maximum. pixel values are rescaled to give the full range of pixel values and the real minimum and maximum are set to the pixel minimum and maximum (unless -real_range is used). this should be equivalent to converting the input to a floating point type and reading it in with -float -oshort (for example) assuming that -real_range is not used.

---

💖 Writing output file

• -2 — create MINC 2.0 format output files.
• -clobber — overwrite existing minc file (this is the default).
• -noclobber — don't overwrite existing minc file. (protective era 🫶)

---

🌟 Reading from input file

• -input inputfile — read input data from inputfile instead of standard input.
• -skip length — skip the first length bytes of the input.

---

🌈 World coordinate conversion

• -xstep xstep — step size for x dimension (default = none).
• -ystep ystep — step size for y dimension (default = none).
• -zstep zstep — step size for z dimension (default = none).
• -xstart xstart — starting coordinate for x dimension (default = none). this is a distance parallel to the axis.
• -ystart ystart — starting coordinate for y dimension (default = none). this is a distance parallel to the axis.
• -zstart zstart — starting coordinate for z dimension (default = none). this is a distance parallel to the axis.
• -xdircos x1 x2 x3 — direction cosines for x dimension (default = none).
• -ydircos y1 y2 y3 — direction cosines for y dimension (default = none).
• -zdircos z1 z2 z3 — direction cosines for z dimension (default = none).
• -origin o1 o2 o3 — specify the spatial coordinates of the first voxel. if the direction cosines are not given or are the default ones, this option will give the same results as using the -start options. otherwise, the coordinate is projected parallel to the axes to determine the appropriate start values.

---

okay bestie, that's part 1 of the lore — the rest is still loading, don't go anywhere 💖

Frame time and length specification ⏰

ok bestie this is where you tell the program how your time frames are laid out, and it's lowkey strict about it:

• -frame_times t1,t2,t3,... — this sets the start of each time frame. The number of values you give has to match the length of the time dimension you specified on the command line, no exceptions. And here's the thing: all the values have to be in one single argument — so no spaces between them, or if you do use spaces, the whole string needs quoting. Separation by spaces instead of commas is permitted, so you have options, but commas are the moment. 💅
• -frame_widths w1,w2,w3,... — this sets the length of each time frame. Everything I just said about -frame_times applies here too, same rules, same energy. 🫶

So like, if you wanna set the start and step values for a functional file with constant frame times, you use the -dattribute flag (described below, keep scrolling bestie) like this:

-dattribute time:step=1 -dattribute time:start=0

periodt, that's the whole vibe for timing. ✨

---

Imaging modality 🩻

Which flavour of scan are we dealing with? Pick your icon:

• -nomodality — do not store the modality type in the file. This is the default, so if you say nothing, this is what you get.
• -pet — PET data.
• -mri — MRI data.
• -spect — SPECT data.
• -gamma — data from a gamma camera.
• -mrs — MR spectroscopy data.
• -mra — MR angiography data.
• -ct — CT data.
• -dsa — DSA data
• -dr — digital radiography data.

main character modality selection fr fr 🌈

---

Attribute specification 🎀

• -sattribute variable:attribute=value — says that variable should be created with a string attribute set to value. The complete spec — variable, attribute and value — has to live in only one argument to the program, so if your string has blanks in it you're gonna need to quote it. 🫶
• -dattribute variable:attribute=value — same as -sattribute, but for specifying double-precision attribute values. numbers girlies rise 💜
• -attribute variable:attribute=value — like -sattribute or -dattribute, except the type gets chosen for you: it first tries to interpret the value as double precision, and if that fails, then it just assumes the value is a string. it's giving "we'll figure it out" 😭

---

Generic options ⭐

• -help — print a summary of the command-line options and exit. your little cheat sheet bestie.
• -version — print the program's version number and exit. 💅

---

AUTHOR 👑

Peter Neelin

---

COPYRIGHTS 📜

Copyright © 1993 by Peter Neelin

---

ok that's the whole page bestie, you ate that 🍓 and just so you know, this one's stamped $Date: 2005-02-09 19:27:18 $ and it's page RAWTOMINC(1) — so if you're citing it, that's the version and the date, iykyk 💖 go forth and convert those raw files, you icon 👑✨