# Modifiers

## AffineTransformationModifier

Scripting interface of the Affine transformation modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`transformation` | `AffineTransformation` | Identity matrix | The 3 x 4 affine transformation matrix. Used only if `relativeMode==true`. The fourth matrix column specifies the translation vector.
`targetCell` | `AffineTransformation` | Zero matrix | The target simulation cell shape. Used only if `relativeMode==false`. This is a 3x4 matrix. The first three columns specify the cell vectors. The fourth column specifies the origin of the simulation box.
`relativeMode` | boolean | `true` | If `true`, the matrix `transformation` is used to transform particles. If `false`, the affine transformation is computed by the modifier from the current simulation cell shape and the target shape matrix `targetCell`.
`applyToSimulationBox` | boolean | false | Controls whether the simulation cell shape is affected by the modifier.
`applyToParticles` | boolean | true | Controls whether the particle positions are affected by the modifier.
`applyToSurfaceMesh` | boolean | false | Controls whether a surface mesh is affected by the modifier.
`selectionOnly` | boolean | false | Set this to `true` to transform only selected particles.

Example:

    // Set up a shear transformation matrix. Start by creating an identity transformation matrix:
    m = new AffineTransformation()
    // Set XZ shear component to 0.1. The XZ element is stored in row 0 and column 2 of the matrix.
    m.setElement(0, 2, 0.1)

    // Apply affine transformation modifier:
    ovito.selectedNode.applyModifier(new AffineTransformationModifier({
    	applyToSimulationBox : true,
    	transformation : m
    }))

WARNING: The following does NOT work, because `setElement()` acts on a copy of the transformation matrix:

    mod = new AffineTransformationModifier()
    mod.transformation.setElement(0, 2, 0.1)

## AmbientOcclusionModifier

Scripting interface of the Ambient occlusion modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`intensity` | number | 0.7 | Controls the strength of the shading effect. Valid range: [0.0,1.0]
`samplingCount` | integer | 20 | Number of exposure samples to compute
`bufferResolution` | integer | 3 | Render buffer resolution. Valid range: [1,4]

## AssignColorModifier

Scripting interface of the Assign color modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`color` | `Color` | `Color(0.3,0.3,1.0)` | The RGB color that will be assigned to selected particles.
`keepSelection` | boolean | `false` | Controls whether the modifier clears the current particle selection or not.

## AtomicStrainModifier

Scripting interface of the Atomic strain modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`cutoff` | number | 3.0 | The range of neighbors.
`eliminateCellDeformation` | boolean | `false` | Controls whether the simulation cell is adjusted prior to the strain calculation.
`assumeUnwrappedCoordinates` | boolean | `false` | Controls the use of the minimum image convention for particles that have crossed a periodic boundary.
`calculateDeformationGradients` | boolean | `false` | Enables the output of all elements of the atomic deformation gradient tensors.
`calculateStrainTensors` | boolean | `false` | Enables the output of all elements of the atomic strain tensors.
`selectInvalidParticles` | boolean | `true` | Enables the selection of particles for which the atomic strain tensor could not be computed.
`invalidParticleCount` | integer | read-only | Number of particles for which the atomic strain tensor could not be computed.
`referenceConfiguration` | `LinkedFileObject` |  | The reference configuration of the particles.

Example:

    modifier = new AtomicStrainModifier({ cutoff : 3.4 })
    modifier.referenceConfiguration.load("simulation.0.dump")
    ovito.selectedNode.applyModifier(modifier)

## BondAngleAnalysisModifier

Scripting interface of the Bond-angle analysis modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`structureCounts` | `Array` | read-only | Array with the number of identified particles per structure type. This array gets filled when the modifier performs the analysis. The following constants can be used to access the array (see example below): `OTHER`, `FCC`, `HCP`, `BCC`, `ICO`.

Example:

    ovito.selectedNode.applyModifier(modifier = new BondAngleAnalysisModifier())
    wait()
    print("Number of FCC atoms: " + modifier.structureCounts[BondAngleAnalysisModifier.FCC])

## CalculateDisplacementsModifier

Scripting interface of the Displacement vectors modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`eliminateCellDeformation` | boolean | `false` | Controls whether the simulation cell is adjusted prior to the displacement calculation.
`assumeUnwrappedCoordinates` | boolean | `false` | Disables the use of the minimum image convention for particles that have crossed a periodic boundary.
`referenceFrameNumber` | integer | 0 | The frame to use as reference configuration if the reference file contains multiple timesteps.
`useReferenceFrameOffset` | boolean | `false` | Enables a sliding reference frame.
`referenceFrameOffset` | integer | -1 | When using a sliding reference frame this sets the offset between the reference frame and the current frame.
`vectorDisplay` | `VectorDisplay` |  | The vector display object controlling the display of displacement arrows.
`referenceConfiguration` | `LinkedFileObject` |  | The reference configuration.

Example:

    modifier = new CalculateDisplacementsModifier({ eliminateCellDeformation : true })
    modifier.referenceConfiguration.load("simulation.0.dump")
    modifier.vectorDisplay.isEnabled = true
    ovito.selectedNode.applyModifier(modifier)

## CentroSymmetryModifier

Scripting interface of the Centrosymmetry parameter modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`numNeighbors` | integer | 12 | Number of particle neighbors taken into account for computing the centrosymmetry value.

## ClusterAnalysisModifier

Scripting interface of the Cluster analysis modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`cutoff` | number | 3.2 | The maximum distance between particles belonging to the same cluster.
`clusterCount` | integer | read-only | After the cluster analysis has been performed, this property field contains the number of identified cluster.

## ColorCodingModifier

Scripting interface of the Color coding modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`sourceProperty` | string |  | The particle property to be used for coloring.
`startValue` | number |  | Start of property value range. Is mapped to the first color.
`endValue` | number |  | End of property value range. Is mapped to the last color.
`colorOnlySelected` | boolean | `false` | If true, colors are only assigned to selected particle while the existing color of other particles is left unchanged.
`keepSelection` | boolean | `false` | Normally, the modifier clears the current particle selection. This flag disables this behavior.
`colorGradient` | `ColorCodingGradient` | `ColorCodingHSVGradient` | The color gradient object that is responsible for mapping property values to colors. The following gradient types are available: `ColorCodingHSVGradient`, `ColorCodingGrayscaleGradient`, `ColorCodingHotGradient`, `ColorCodingJetGradient`.

Example:

    ovito.selectedNode.applyModifier(new ColorCodingModifier({
    	sourceProperty : "Displacement.X",
    	colorGradient : new ColorCodingHotGradient()
    }))

## CommonNeighborAnalysisModifier

Scripting interface of the Common neighbor analysis modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`adaptiveMode` | boolean | `true` | Activates the adaptive version of the CNA, which determines the cutoff radius for each particle individually.
`cutoff` | number | 3.2 | The cutoff radius for the conventional CNA. This is ignored if `adaptiveMode==true`
`structureCounts` | `Array` | read-only | Array with the number of particles found for each structure type. This array gets filled when the modifier performs the analysis. The following constants can be used to access the array (see example below): `OTHER`, `FCC`, `HCP`, `BCC`, `ICO`, `DIA`.

Example:

    ovito.selectedNode.applyModifier(modifier = new CommonNeighborAnalysisModifier({
    	adaptiveMode : false,
    	cutoff : 3.411
    }))
    wait()
    print("Number of FCC atoms: " + modifier.structureCounts[CommonNeighborAnalysisModifier.FCC])

## ConstructSurfaceModifier

Scripting interface of the Construct surface mesh modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`radius` | number | 4.0 | Radius of the virtual probe sphere
`smoothingLevel` | integer | 8 | Number of smoothing iterations
`onlySelectedParticles` | boolean | `false` | If true, the surface is constructed only from selected particles.
`surfaceArea` | number | read-only | After the modifier has constructed the surface, this output field contains the computed surface area.
`solidVolume` | number | read-only | After the modifier has constructed the surface, this output field contains the computed solid volume.
`totalVolume` | number | read-only | After the modifier has constructed the surface, this output field contains volume of the simulation cell.

## CoordinationNumberModifier

Scripting interface of the Coordination analysis modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`cutoff` | number | 3.2 | The maximum distance up to which two particlea are considered neighbors.

## CreateBondsModifier

Scripting interface of the Create bonds modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`uniformCutoff` | number | 3.2 | Controls which particle are connected by a bond.

## CreateExpressionPropertyModifier

Scripting interface of the Compute property modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`outputProperty` | string | `"Custom property"` | The name of the output particle property.
`onlySelectedParticles` | boolean | `false` | Restricts the computation of property values to selected particles.
`expressions` | array of strings | `["0"]` | The list of math expressions. The size of the array must match the number of vector components of the output property.

Example:

    ovito.selectedNode.applyModifier(new CreateExpressionPropertyModifier({
    	outputProperty : "Radius",
    	expressions : [ "ParticleType==2 ? 1.6 : 1.2" ]
    }))

## FreezePropertyModifier

Scripting interface of the Freeze property modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`sourceProperty` | string |  | The particle property to be frozen.
`destinationProperty` | string |  | The name of the output particle property.

## SelectExpressionModifier

Scripting interface of the Expression select modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`expression` | string |  | The Boolean expression

## ShowPeriodicImagesModifier

Scripting interface of the Show periodic images modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`showImageX` | boolean | `false` | Enables the generation of copies in the X direction.
`showImageY` | boolean | `false` | Enables the generation of copies in the Y direction.
`showImageZ` | boolean | `false` | Enables the generation of copies in the Z direction.
`numImagesX` | integer | 3 | The number of periodic images to generate in the X direction (including the primary image).
`numImagesY` | integer | 3 | The number of periodic images to generate in the Y direction (including the primary image).
`numImagesZ` | integer | 3 | The number of periodic images to generate in the Z direction (including the primary image).
`adjustBoxSize` | boolean | `false` | This flag controls the resizing of the simulation cell.

## SliceModifier

Scripting interface of the Slice modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`normal` | `Vector` | `Vector(1,0,0)` | The normal vector of the slicing plane.
`distance` | number | 0 | The (signed) distance of the slicing plane from the origin along the plane's normal.
`sliceWidth` | number | 0 | The width of the slice to take.
`inverse` | boolean | `false` | This flag flips the orientation of the slicing plane.
`createSelection` | boolean | `false` | If true, the modifier selects particles instead of deleting them.
`applyToSelection` | boolean | `false` | If true, the modifier removes/selects only particles that are currently selected.

## WignerSeitzAnalysisModifier

Scripting interface of the Wigner-Seitz defect analysis modifier:

Property | Data type | Default value | Description
--- | --- | --- | ---
`eliminateCellDeformation` | boolean | `false` | Controls whether the simulation cell is adjusted to match the reference cell prior to the analysis.
`referenceFrameNumber` | integer | 0 | The frame to use as reference configuration if the reference file contains multiple timesteps.
`useReferenceFrameOffset` | boolean | `false` | Enables a sliding reference frame.
`referenceFrameOffset` | integer | -1 | When using a sliding reference frame this sets the offset between the reference frame and the current frame.
`referenceConfiguration` | `LinkedFileObject` |  | The reference configuration.
`vacancyCount` | integer | read-only | This output field contains the number of vacancies identified during the Wigner-Seitz analysis.
`interstitialCount` | integer | read-only | This output field contains the number of interstitials identified during the Wigner-Seitz analysis.

Example:

    modifier = new WignerSeitzAnalysisModifier({ eliminateCellDeformation : true })
    modifier.referenceConfiguration.load("simulation.0.dump")
    ovito.selectedNode.applyModifier(modifier)
    wait()
    print("Found " + modifier.vacancyCount + " vacancies")