# Representation Components

## vtk_geometryrepresentation

The properties available on the vtk_geometryrepresentation let you tune the way you want to render your geometry.

In VTK a representation is composed of an Actor, a Mapper and a Property. Each of those objects can be configured using the actor, mapper and property arguments of the vtk_geometryrepresentation.

The list below shows the default values for each argument:

- actor:
  - origin = (0,0,0)
  - position = (0,0,0)
  - scale = (1,1,1)
  - visibility = 1
  - pickable = 1
  - dragable = 1
  - orientation = (0,0,0)
- property:
  - lighting = true
  - interpolation = Interpolation.GOURAUD
  - ambient = 0
  - diffuse = 1
  - specular = 0
  - specularPower = 1
  - opacity = 1
  - edgeVisibility = false
  - lineWidth = 1
  - pointSize = 1
  - backfaceCulling = false
  - frontfaceCulling = false
  - representation = Representation.SURFACE
  - color = (1,1,1) # White
  - ambientColor = (1,1,1)
  - specularColor = (1,1,1)
  - diffuseColor = (1,1,1)
  - edgeColor = (0,0,0) # Black
- mapper:
  - static = false
  - scalarVisibility = true
  - scalarRange = 0, 1
  - useLookupTableScalarRange = false
  - colorMode = 0 (Available values)
  - scalarMode = 0 (Available values)
  - arrayAccessMode = 1 (Available values)
  - colorByArrayName = ''
  - interpolateScalarsBeforeMapping = false
  - useInvertibleColors = false
  - fieldDataTupleId = -1
  - viewSpecificProperties = None
  - customShaderAttributes = []

On top of those previous settings we provide additional properties to configure a lookup table using one of our available colorMapPreset and a convenient colorDataRange to rescale to color map to your area of focus.

With the vtk_geometryrepresentation you also have the option to turn on the CubeAxes using the `showCubeAxes=True` along with additional configuration parameters that can be provided via the `cubeAxesStyle` property. The content of the object for cubeAxesStyle can be found in the source code of vtk.js from the default section here.

## vtk_glyphrepresentation

vtk_glyphrepresentation lets you use a source as a Glyph which will then be cloned and positioned at every point of another source. The properties available on the vtk_glyphrepresentation let you tune the way you want to render your geometry.

In VTK a representation is composed of an Actor, a Mapper and a Property. Each of those objects can be configured using the actor, mapper and property arguments of the vtk_glyphrepresentation.

The list below shows the default values for each argument:

- actor:
  - origin = (0,0,0)
  - position = (0,0,0)
  - scale = (1,1,1)
  - visibility = 1
  - pickable = 1
  - dragable = 1
  - orientation = (0,0,0)
- property:
  - lighting = true
  - interpolation = Interpolation.GOURAUD
  - ambient = 0
  - diffuse = 1
  - specular = 0
  - specularPower = 1
  - opacity = 1
  - edgeVisibility = false
  - lineWidth = 1
  - pointSize = 1
  - backfaceCulling = false
  - frontfaceCulling = false
  - representation = Representation.SURFACE
  - color = (1,1,1) # White
  - ambientColor = (1,1,1)
  - specularColor = (1,1,1)
  - diffuseColor = (1,1,1)
  - edgeColor = (0,0,0) # Black
- mapper:
  - orient = true
  - orientationMode = 0 (Available values)
  - orientationArray = null
  - scaling = true
  - scaleFactor = 1.0
  - scaleMode = 1 (Available values)
  - scaleArray = nothing
  - static = false
  - scalarVisibility = true
  - scalarRange = 0, 1
  - useLookupTableScalarRange = false
  - colorMode = 0 (Available values)
  - scalarMode = 0 (Available values)
  - arrayAccessMode = 1 (Available values)
  - colorByArrayName = ''
  - interpolateScalarsBeforeMapping = false
  - useInvertibleColors = false
  - fieldDataTupleId = -1
  - viewSpecificProperties = nothing
  - customShaderAttributes = []

On top of those previous settings we provide additional properties to configure a lookup table using one of our available colorMapPreset and a convenient colorDataRange to rescale to color map to your area of focus.

An example of the vtk_glyphrepresentation could be creating a spiky sphere by positioning cones normal to the sphere.

    function Example()
      return vtk_view(
        children=[
            vtk_glyphrepresentation(
                mapper=Dict("orientationArray" => "Normals"),
                children=[
                    vtk_algorithm(
                        port=0,
                        vtkClass="vtkSphereSource",
                        state=Dict(
                            "phiResolution" => 10,
                            "thetaResolution" => 20,
                        ),
                    ),
                    vtk_algorithm(
                        port=1,
                        vtkClass="vtkConeSource",
                        state=Dict(
                            "resolution" => 30,
                            "height" => 0.25,
                            "radius" => 0.08,
                        },
                    ),
                ]
            )
        ]
        )
      end

## vtk_volumerepresentation

The properties available on the vtk_volumerepresentation let you tune the way you want to render your volume.

In VTK a representation is composed of a Volume, a Mapper and a Property. Each of those objects can be configured using the actor, mapper and property arguments of the vtk_geometryrepresentation.

The list below shows the default values for each argument:

- volume:
  - origin = (0,0,0)
  - position = (0,0,0)
  - scale = (1,1,1)
  - visibility = 1
  - pickable = 1
  - dragable = 1
  - orientation = (0,0,0)
- property:
  - independentComponents = true
  - interpolationType = InterpolationType.FAST_LINEAR
  - shade = 0
  - ambient = 0.1
  - diffuse = 0.7
  - specular = 0.2
  - specularPower = 10.0
  - useLabelOutline = false
  - labelOutlineThickness = 1
  - useGradientOpacity = idx, value
  - scalarOpacityUnitDistance = idx, value
  - gradientOpacityMinimumValue = idx, value
  - gradientOpacityMinimumOpacity = idx, value
  - gradientOpacityMaximumValue = idx, value
  - gradientOpacityMaximumOpacity = idx, value
  - opacityMode = [idx, value]
- mapper:
  - sampleDistance = 1.0
  - imageSampleDistance = 1.0
  - maximumSamplesPerRay = 1000
  - autoAdjustSampleDistances = true
  - blendMode = BlendMode.COMPOSITE_BLEND
  - averageIPScalarRange = -1000000.0, 1000000.0

On top of those previous settings we provide additional properties to configure a lookup table using one of our available colorMapPreset and a convenient colorDataRange to rescale to color map to your area of focus.

Because it can be cumbersome and difficult to properly configure your volume rendering properties, it is convenient to add as first child to that representation a vtk_volumecontroller which will give you a UI to drive some of those parameters while also providing better defaults for your vtk_imagedata.

## vtk_volumecontroller

The vtk_volumecontroller provide a convenient UI element to control your Volume Rendering settings and can be tuned with the following set of properties:

- size: width, height in pixel for the controller UI
- rescaleColorMap: true/false to use the opacity piecewise function to dynamically rescale the color map or keep the full data range as color range.

## vtk_slicerepresentation

The __vtk_slicerepresentation lets you see a slice within a 3D image. That slice can be along i,j,k or x,y,z if your volume contains an orientation matrix.

The following set of properties lets you pick which slice you want to see. Only one of those properties can be used at a time.

- iSlice, jSlice, kSlice: Index based slicing
- xSlice, ySlice, zSlice: World coordinate slicing

Then we have the standard representation set or properties with their defaults:

- actor:
  - origin = (0,0,0)
  - position = (0,0,0)
  - scale = (1,1,1)
  - visibility = 1
  - pickable = 1
  - dragable = 1
  - orientation = (0,0,0)
- property:
  - independentComponents = false
  - interpolationType = InterpolationType.LINEAR
  - colorWindow = 255
  - colorLevel = 127.5
  - ambient = 1.0
  - diffuse = 0.0
  - opacity = 1.0
- mapper:
  - customDisplayExtent: 0, 0, 0, 0
  - useCustomExtents: false
  - slice: 0
  - slicingMode: SlicingMode.NONE
  - closestIJKAxis: { ijkMode: SlicingMode.NONE, flip: false }
  - renderToRectangle: false
  - sliceAtFocalPoint: false

## vtk_pointcloudrepresentation

The vtk_pointcloudrepresentation is just a helper using the following structure to streamline rendering a point cloud dataset. The code snippet below is not complete but it should provide you with some understanding of the kind of simplification that is happening under the hood.

    function vtk_pointcloudrepresentation(; kwargs...)
      return vtk_geometryrepresentation(
          id=kwargs.id,
          colorMapPreset=kwargs.colorMapPreset,
          colorDataRange=kwargs.colorDataRange,
          property=kwargs.property,
          children=[
            vtk_polydata(
                points=kwargs.xyz,
                connectivity="points",
                children=[
                  vtk_pointdata([
                      vtk_dataarray(
                        registration="setScalars",
                        values=kwargs.scalars,
                      )
                  ])
                ],
            )
          ],
      )
    end

The set of convenient properties are as follows:

- xyz = list of xyz of each point inside a flat array
- colorMapPreset = color preset name to use
- colorDataRange = rescale color map to provided that range
- property = {} # Same as GeometryRepresentation/property
- rgb / rgba / scalars = `[...]` let you define the field you want to color your point cloud with. The rgb(a) expects numbers up to 255 for each component: Red Green Blue (Alpha).

## vtk_volumedatarepresentation

The vtk_volumedatarepresentation is just a helper using the following structure to streamline rendering a volume. The code snippet below is not complete but it should provide you with some understanding of the kind of simplification that is happening under the hood.

    function vtk_volumedatarepresentation(; kwargs...)
      return dash_vtk.VolumeRepresentation(
          id=kwargs.id,
          colorMapPreset=kwargs.colorMapPreset,
          colorDataRange=kwargs.colorDataRange,
          property=kwargs.property,
          mapper=kwargs.mapper,
          volume=kwargs.volume,
          children=[
              vtk_volumecontroller(
                  rescaleColorMap=kwargs.rescaleColorMap,
                  size=kwargs.size,
              ),
              vtk_imagedata(
                  dimensions=kwargs.dimensions,
                  origin=kwargs.origin,
                  spacing=kwargs.spacing,
                  children=[
                      vtk_pointdata([
                          vtk_dataarray(
                              registration="setScalars",
                              values=kwargs.scalars,
                          )
                      ])
                  ],
              ),
          ],
      )
    end

The set of convenient properties are as follows:

- dimensions: Number of points along x, y, z
- spacing: Spacing along x, y, z between points in world
- origin: World coordinate of the lower left corner of your vtkImageData (i=0, j=0, k=0).
- rgb: Use RGB values to attach to the points/vertex
- rgba: Use RGBA values to attach to the points/vertex
- scalars: Field values to attach to the points
- scalarsType: Types of numbers provided in scalars (i.e. Float32Array, Uint8Array, ...)
- mapper: Properties to set to the mapper
- volume: Properties to set to the volume
- property: Properties to set to the volume.property
- colorMapPreset: Preset name for the lookup table color map
- volumeController: Show volumeController
- controllerSize: Controller size in pixels
- rescaleColorMap: Use opacity range to rescale color map