Page MenuHomePhabricator

Documentation for properties
Closed, ResolvedPublic

Description

For MITK properties should be documented what they are doing.

Currently, there are some "weird" properties. For instance, "use color" seems to decide whether a lookup-table is used for rendering or the color which can be set to the node on right click. However, by default the lookup-table is set to standard CT gray values and if you disable the property "use color" the former gray image becomes colored, because now a default RGB color lookup-table will be used. As a consequence, the behavior of this property is really confusing for new users and should be documented well (and probably renamed).

An other example is this documentation from the mitkImageMapperGL2D in line 73 " "in plane resample extent by geometry": (BoolProperty) Do it or not".

Furthermore, we should precisely define the desired behavior of properties if they are used in combination with others. There are huge code parts to act according to the properties but we have no document which actually defines what should happened.

Related Objects

StatusAssignedTask
ResolvedNone
ResolvedNone
ResolvedNone
ResolvedNone
ResolvedNone
ResolvedNone
ResolvedNone

Event Timeline

Everyone is invited to take care of this one. Feel free to assign it to you, delightful reader. ;)

We will go through the properties and try to determine what each one does. Feel free to help, but coordination could be a key here....

Just loaded an image, the shown properties are:

LookupTable
TransferFunction
binary
bounding box
color
in plane resample extent by geometry
layer
levelwindow
name
opacity
outline binary
outline width
path
reslice interpolation
selected
texture interpolation
use color
visible
volumerendering
volumerendering configuration
volumerendering.cpu.ambient
volumerendering.cpu.diffuse
volumerendering.cpu.specular
volumerendering.cpu.specular.power
volumerendering.gpu.ambient
volumerendering.gpu.diffuse
volumerendering.gpu.specular
volumerendering.gpu.specular.power
volumerendering.gpu.reducesliceartifacts
volumerendering.gpu.usetexturecompression
volumerendering.ray.ambient
volumerendering.ray.diffuse
volumerendering.ray.specular
volumerendering.ray.specular.power
volumerendering.usegpu
volumerendering.uselod
volumerendering.usemip
volumerendering.useray

Loading a surface gives:

back color
back normal length (px)
color
color mode
draw normals 2d
front color
front normal lenth (px)
invert normals
layer
linewidth
material.ambientCoefficient
material.diffuseCoefficient
material.interpolation
material.representation
material.specularCoefficient
material.specularPower
material.wireframeLineWidth
name
opacity
path
scalar mode
scalar visibility
selected
shader
visible

Vesseltree has:
Render skeleton
VesselTreeLookupTable
layer
name
path
selected
visible

PointSet:
close contour
color
contourcolor
contoursize
distance decimal digits
layer
line width
name
path
point 2D size
point line width
pointsize
selected
selectedcolor
show angles
show contour
show distances
show distance lines
show points
updateDataOnRender
visible

segmentation adds to the image properties:
binaryimage.hoveringannotationcolor
binaryimage.hoveringcolor
binaryimage.selectedannotationcolor
binaryimage.selectedcolor
segmentation
showVolume

Planar Figures have:
ClosedPlanarPolygon
layer
name
planarfigure.ishovering
selected
visible

As I am not familiar with all of these properties I would suggest to order them into fitting categories and distributing those as sub-bugs to more competent persons.

My suggested division would be (including what I know about the properties):

..Filesystem:

path - The physical path the file was loaded from
name - The node name in the datamanager

..Generic MITK/imaging property:
color - color the surface, grey value image, whatever should be rendered in (usually white)
layer - controls what image is considered "on top" of another in case two should inhabit the same space, higher layer occludes lower layer
opacity - alpha value of the node/image/surface
selected - Whether the node is selected in the datamanager
visible - toggle node/image/surface being rendered at all

..Volumerendering:
volumerendering - Boolean: Should the volume be rendered or not
volumerendering configuration - Choice between Composite und MIP - ???
volumerendering.cpu.ambient - ambient lighting
volumerendering.cpu.diffuse - in-/decrease light dispersion
volumerendering.cpu.specular - in-/decrease non-scattered reflection
volumerendering.cpu.specular.power - control percentage of non-scattered reflection - ??? difference to just specular?
volumerendering.gpu.ambient - same as cpu with gpu
volumerendering.gpu.diffuse - same as cpu with gpu
volumerendering.gpu.reducesliceartifacts - presumably what the name suggests - ???
volumerendering.gpu.specular - same as cpu with gpu
volumerendering.gpu.specular.power - same as cpu with gpu
volumerendering.gpu.usetexturecompression - presumably what the name suggests - ???
volumerendering.ray.ambient - same as cpu with ray
volumerendering.ray.diffuse - same as cpu with ray
volumerendering.ray.specular - same as cpu with ray
volumerendering.ray.specular.power - same as cpu with ray
volumerendering.usegpu - Boolean: Whether to use the GPU for rendering or not
volumerendering.uselod - Boolean: Whether to use the Level Of Detail mechanism or not
volumerendering.usemip - Boolean: Whether to utilize maximum intensity projection
volumerendering.useray - Boolean: Whether to use raycasting or not

.Additional comment:
uselod can be active with usegpu, usemip, useray, but any of the latter can not be used with another one of them.

..Surfacerendering:
back color - in 2D, color of the normals outside the surface
back normal lenth (px) - in 2D, length of the normals in pixels - Missing "g"? (When decreasing it the color using the front color is shorter?)
draw normals 2d - Boolean: in 2D, toggles the presence of normals
front color - in 2D, color of the normals inside the surface
front normal lenth (px) - in 2D, length of the normals in pixels - Missing "g"? (When decreasing it the color using the back color is shorter?)
invert normals - in 2D, switch front/back normals
line width - in 2D, controls the thickness of the line where the surface intersects the plane (and normals)
material.ambientCoefficient - in 3D ambient lighting
material.diffuseCoefficient - in 3D scattering of light
material.interpolation - Choose which interpolation algorithm to use for surface construction
material.representation - Choose the representation to draw the mesh in (Surface, Wireframe, Point Cloud)
material.specularCoefficient - in-/decrease non-scattered reflection
material.specularPower - control percentage of non-scattered reflection - ??? difference to specularCoefficient?
material.wireframeLineWidth - width of the wires if wireframe representation is selected
shader - which shader to use for surface rendering, currently the options are "fixed" and "mitkShaderLightning"

..Unknown:
color mode - surface - ???
scalar mode - surface - ???
scalar visibility - surface - ???

binary
binaryimage.hoveringannotationcolor
binaryimage.hoveringcolor
binaryimage.selectedannotationcolor
binaryimage.selectedcolor
bounding box
close contour
ClosedPlanarPolygon
contourcolor
contoursize
distance decimal digits
in plane resample extent by geometry
levelwindow
linewidth
LookupTable
outline binary
outline width
planarfigure.ishovering
point 2D size
point line width
pointsize
Render skeleton
reslice interpolation
segmentation
selectedcolor
show angles
show contour
show distance lines
show distances
show points
showVolume
texture interpolation
TransferFunction
updateDataOnRender
use color
VesselTreeLookupTable

W.I.P.

So a first quick description and categorization

As I am not familiar with all of these properties I would suggest to order them into fitting categories and distributing those as sub-bugs to more competent persons.

My suggested division would be (including what I know about the properties):

..Filesystem:

path - The physical path the file was loaded from
name - The node name in the datamanager

..Generic MITK/imaging property:
color - color the surface, grey value image, whatever should be rendered in (usually white)
layer - controls what image is considered "on top" of another in case two should inhabit the same space, higher layer occludes lower layer
levelwindow - contains the level window of the image
LookupTable - contains lookuptable for use in coloring image
opacity - alpha value of the node/image/surface
selected - Whether the node is selected in the datamanager
texture interpolation - toggle interpolation
TransferFunction - contains transfer function for use in coloring image
use color - Toggle whether LUT is used (off) or not (on) - Should be redone and renamed, this is counterintuitive
visible - toggle node/image/surface being rendered at all

..Planarfigures:
ClosedPlanarPolygon - is the polygon closed
planarfigure.ishovering - ???

..PointSets:
close contour - ???
contourcolor - color of the contour (if active)
contoursize - how thick is the contour (if active)
distance decimal digits - if show distance is active, how decimal places are shown
point 2D size - in 2D, how big are the points (how long are the arms of the crosses)
point line width - in 2D how thick are the lines
pointsize - in 3D - control the sphere radius
selectedcolor - ???
show angles - if contour, print angle between two pieces
show contour - draw connecting pieces between dots
show distance lines - show angles/lines even if not on current slice
show distances - draw length of connecting elements
show points - toggle points
updateDataOnRender - ???

..Reslicing (when rendering slices which are not parallel to the original image axes)
reslice interpolation - Select interpolation mode (Nearest, Linear, Cubic)
in plane resample extent by geometry - ???

..Segmentations:
binary - Toggle whether the image is treated as a binary/segmentation image
binaryimage.hoveringannotationcolor - ???
binaryimage.hoveringcolor - ???
binaryimage.selectedannotationcolor - ???
binaryimage.selectedcolor - The color the surface is rendered in 2D while selected
outline binary - Toggle whether the segmentation is drawn as an outline (on) or solid (off)
outline width - width of the outline
showVolume - Toggle whether the volume of the segmentation is shown in the 2D views

..Surfacerendering:
back color - in 2D, color of the normals outside the surface
back normal lenth (px) - in 2D, length of the normals in pixels - Missing "g"? (When decreasing it the color using the front color is shorter?)
draw normals 2d - Boolean: in 2D, toggles the presence of normals
front color - in 2D, color of the normals inside the surface
front normal lenth (px) - in 2D, length of the normals in pixels - Missing "g"? (When decreasing it the color using the back color is shorter?)
invert normals - in 2D, switch front/back normals
line width - in 2D, controls the thickness of the line where the surface intersects the plane (and normals)
material.ambientCoefficient - in 3D ambient lighting
material.diffuseCoefficient - in 3D scattering of light
material.interpolation - Choose which interpolation algorithm to use for surface construction
material.representation - Choose the representation to draw the mesh in (Surface, Wireframe, Point Cloud)
material.specularCoefficient - in-/decrease non-scattered reflection
material.specularPower - control percentage of non-scattered reflection - ??? difference to specularCoefficient?
material.wireframeLineWidth - width of the wires if wireframe representation is selected
shader - which shader to use for surface rendering, currently the options are "fixed" and "mitkShaderLightning"

..Unknown:
bounding box - Boolean - ???
color mode - surface - ???
scalar mode - surface - ???
scalar visibility - surface - ???
segmentation - ???

..Vesseltrees
Render skeleton - toggle rendering as skeleton (on) or surface (off)
VesselTreeLookupTable - contains lookuptable for the different vessel tree segments (arteries can be colored differently from venes and so on)

..Volumerendering:
volumerendering - Boolean: Should the volume be rendered or not
volumerendering configuration - Choice between Composite und MIP - ???
volumerendering.cpu.ambient - ambient lighting
volumerendering.cpu.diffuse - in-/decrease light dispersion
volumerendering.cpu.specular - in-/decrease non-scattered reflection
volumerendering.cpu.specular.power - control percentage of non-scattered reflection - ??? difference to just specular?
volumerendering.gpu.ambient - same as cpu with gpu
volumerendering.gpu.diffuse - same as cpu with gpu
volumerendering.gpu.reducesliceartifacts - presumably what the name suggests - ???
volumerendering.gpu.specular - same as cpu with gpu
volumerendering.gpu.specular.power - same as cpu with gpu
volumerendering.gpu.usetexturecompression - presumably what the name suggests - ???
volumerendering.ray.ambient - same as cpu with ray
volumerendering.ray.diffuse - same as cpu with ray
volumerendering.ray.specular - same as cpu with ray
volumerendering.ray.specular.power - same as cpu with ray
volumerendering.usegpu - Boolean: Whether to use the GPU for rendering or not
volumerendering.uselod - Boolean: Whether to use the Level Of Detail mechanism or not
volumerendering.usemip - Boolean: Whether to utilize maximum intensity projection
volumerendering.useray - Boolean: Whether to use raycasting or not

.Additional comment:
uselod can be active with usegpu, usemip, useray, but any of the latter can not be used with another one of them.

Anyone missing a property she feels should be on the list, do not hesitate to leave a comment.

Answers so far:
..PointSets:
close contour – Wenn draw contour aktiv ist, werden Linien zwischen den Punkten gezeichnet. Wenn close contour aktiv ist, dann wird der letzte Punkt und der erste verbunden.
selectedcolor – Farbe für die selektierten Punkte (Standard gelb)

-> Close contour should do what the name suggests, it just does not work, created T8155.

hovering/ishovering/hoveringcolor seems to be used by some interactors for changing colors when the mouse hovers over an object.

TODO: What does opaclevelwindow? It is only used in ImageMapperGL2D.

Just a suggestion: We should use this opportunity and rename it to opaquelevelwindow.

As for the renaming suggestion, the same goes for any of the lenth variables in my opinion.

Further answers:
segmentation:

ist eine BoolProperty die gesetzt wird, wenn eine neue Segmentierung erzeugt wird.

in plane resample extent by geometry:

Im mitkImageMapperGL2D gibt es eine entsprechende Membervariable, die entsprechend dem Wert dieser Property gesetzt wird. (Zeile 424) Mit ihr wird das Abtastgitter für das Reslicing festgelegt.

To renaming:
We should rename "use color" to something that indicates that ONLY if use color=false MITK uses the lookuptable to render images etc..

We found more "unknown" (or useless) properties in the Geometry2DDataVtkMapper3D:
"surfacegeometry"
"levelWindow" <- the default property is "levelwindow", however some mappers also check if "levelWindow" is set and there are actually parts in MITK setting it (e.g. RegionGrow3DTool) ... We should clarify this.

Some more research:

bounding box - In theory this should decide whether a bounding box is dran or not (see mitkVolumeDataVtkMapper3D.cpp ) but it seems it is used nowhere but for the mitkImageMapperGL2D.cpp, where it is set to false.
Checking it manually does not do anything as far as I can tell.

Should be done for now, barring any suddenly changing properties.

kislinsk reopened subtask Restricted Maniphest Task as Open.Jun 27 2018, 3:01 PM
kislinsk closed subtask Restricted Maniphest Task as Resolved.Jun 27 2018, 3:27 PM