CIBC:Documentation:SCIRun:ModuleRenaming

SCIRun Module Renaming

The goal is to make module names intuitive and consistent, so new users will more easily be able to: 1) find a module based on what they're trying to accomplish; and 2) correctly guess what a module does based on its name. This process also involves renaming some of the Categories and migrating modules between categories.

Here are a few example of old names and new names:

	FieldReader -> ReadField
	Isosurface -> ExtractIsosurface
	MatlabInterface -> InterfaceWithMatlab
	MatrixInfo -> ReportMatrixInfo
	Viewer -> ViewScene

As you can see, the naming scheme is basically: VERB NOUN.

I tried hard to come up with a set of descriptive and intuitive verbs, as well as consistent conventions for when to use each. Here are the VERBS:

VERB = Read | Write | Import | Export | Create |
			Get | Set | ( Extract | Clip | Split ) | ( Insert | Join | Merge | Append ) |
			Transform {only for geometry} |
			Convert {one datatype to another -- just change representation, not values} |
                        Generate {new Geom} | Calculate {new FData} | Build {not Geom or FData}
			Apply | Edit | Map |
			Show | View |
			Report |
			Select {was "choose"} |
			InterfaceWith |
			Synchronize |
			Print |
			Evaluate | Simulate | Optimize | Solve |
			Mask | Smooth | Coregister | Absorb | Classify

-- the parenthetical groupings are meant to highlight similarities, whereas the braces are just comments.

Here's the definition (and an example) for each VERB:

Read: Read a file type that SCIRun is familiar with from disk. e.g. ReadField

Write: Write a file type that SCIRun knows about to disk. e.g. WriteField

Import: Read a file type that SCIRun can't handle by converting it. e.g. ImportNrrdFromDICOM

Export: Write a file type that SCIRun can't handle by converting it. e.g. ExportImage

Create: Generate a SCIRun dataflow object from scratch. e.g. CreateStandardColorMaps

Get: Return a simple subset of the input, for example the boundary of a field or a column of a dense matrix. e.g. GetFieldsFromBundle

Set: Set a simple value (add it if needed, for example as a Property). e.g. SetNrrdProperty

Extract, Clip, Split: more specific / complicated operations than Get. e.g. ClipLatVolByIndices, ExtractPlanarSliceFromField, SplitFileName

Insert, Join, Merge, Append, Collect: just what they sound like. Insert puts one thing into another (e.g. a field into a Bundle); Join groups a bunch of things without checking for duplicates or intersections or anything; Merge is like Join except it is more careful (e.g. it does check for duplicates and intersections); Append just adds something to the end (like AppendMatrix); Collect is a merge over time (each iteration more things get added). Examples: InsertFieldsIntoBundle, JoinFields, MergeTriSurfs, AppendMatrix, CollectMatrices

Transform: transform a mesh -- note, this term is only used for geometry now (not for field data) e.g. TransformMeshWithFunction

Convert: convert from one dataflow type to another e.g. ConvertQuadSurfToTriSurf, ConvertMatricesToMesh

Generate: create a new Field from an existing one e.g. GeneratePointSampleFromField, GenerateStreamLines

Calculate: assign new Field data values based on some algorithm e.g. CalculateVectorMagnitudes, CalculateMisfitField, CalculateFieldData2 (used to be TransformData2)

Build: for creating things that aren't Fields e.g. BuildFEMatrix, BuildNrrdGradients, BuildMappingMatrix

Apply: for applying electric sources and also for applying mapping matrices e.g. ApplyMappingMatrix, ApplyFEMVoltageSource

Edit: change parameters via a user interface e.g. EditMeshBoundingBox, CreateAndEditColorMap, ShowAndEditDipoles

Map: transfer data from one object to another e.g. MapFieldDataToNodeCoordinate, MapFieldDataFromSourceToDestination

Show, View, Graph: Show creates a renderable object from various dataflow types, View is used to actually objects e.g. ShowField, ShowMeshBoundingBox (used to be FieldCage), ViewScene (used to be Viewer), ViewGraph

Report: Informational modules e.g. ReportFieldInfo, ReportScalarFieldStats

Select: for taking in several dataflow objects of a single type and just sending one downstream (used to be Choose) e.g. SelectField, SelectColorMap

InterfaceWith: modules for communicating with other projects e.g. InterfaceWithMatlab, InterfaceWithTetGen

Synchronize: synchronizes otherwise asynchronously rendered geometry e.g. SynchronizeGeometry

Print: Print is for creating strings from data e.g. PrintMatrixIntoString

Evaluate: linear algebra modules e.g. EvaluateLinAlgBinary

Solve: solve various types of linear algebra systems e.g. SolveLinearSystem, SolveInverseProblemWithTikhonov

Simulate: analytic modeling of electromagnetic fields e.g. SimulateEITAnalytically SimulateDipoleInSphereAnalytically

Optimize: driver modules for simplex-based optimization e.g. OptimizeConductivities, OptimizeDipole

Mask, Smooth, Coregister, Absorb, Classify: very specific modeling modules e.g. MaskLatVolWithTriSurf, SmoothMesh, AbsorbSegFieldIslands, ClassifyHeadTissuesFromMultiMRI

I could go into detail about the NOUNS in the module names, but I'll spare you that. ;) Basically, we just choose the noun that's maximally specific (if a module only works with LatVols, we specify that (e.g. ClipLatVolByIndices) ). When referring to a field's data, we use the phrase FieldData (e.g. ConvertFieldDataFromTensorsToIndices), whereas when we're referring to its geometry we just use the term Mesh (e.g. TransformMeshWithFunction). And, as you've seen in the many examples above, we typically end the module name with a prepositional phrase or other description to better convey exactly what the module does.

Lastly, a few of the Category names have changed. Specifically, the ones that started with Field have been renamed:

	FieldsCreate  ->  NewField
	FieldsData  ->  ChangeFieldData
	FieldsGeometry  -> ChangeMesh
	FieldsOther  ->  MiscField