schema_version: 0.3
type: filter
identifier: vidstab
title: Vid.Stab Detect and Transform
copyright: Jakub Ksiezniak
creator: Marco Gittler <g.marco@freenet.de>
version: 2
license: GPL
language: en
url: http://public.hronopik.de/vid.stab/
tags:
  - Video
description: Stabilize Video (for wiggly/rolling video)
notes: >
  This filter requires two passes. The first pass performs analysis and stores
  the result in a file. Upon successful completion of the analysis, the 
  "results" property is updated with the name of the file storing the results.
  The second pass applies the results to the image.
  
  To use with melt, use 'melt ... -consumer xml:output.mlt all=1 real_time=-1' for the
  first pass. Parallel processing (real_time < -1 or > 1) is not supported for
  the first pass. For the second pass, use output.mlt as the input.

parameters:
  - identifier: results
    title: Analysis Results
    type: string
    description: >
      Set after analysis. Used during application.
      A set of image motion information that describes the analyzed clip.
      When results are not supplied, the filter computes the results and stores
      them in a file. This property is updated with the name of that file when 
      the last frame has been processed.
    mutable: no

  - identifier: filename
    title: Target File Name
    type: string
    description: >
      Used during analysis.
      The name of the file to store the analysis results in.
    required: no
    readonly: no
    default: vidstab.trf
    widget: fileopen

  - identifier: shakiness
    title: Shakiness
    type: integer
    description: >
      Used during analysis.
      How shaky the video is.
    readonly: no
    required: no
    minimum: 1
    maximum: 10
    default: 4
    mutable: no
    widget: spinner

  - identifier: accuracy
    title: Accuracy
    type: integer
    description: >
      Used during analysis.
      The accuracy of shakiness detection.
    readonly: no
    required: no
    minimum: 1
    maximum: 15
    default: 4
    mutable: no
    widget: spinner

  - identifier: stepsize
    title: Stepsize
    type: integer
    description: >
      Used during analysis.
      The step size of the search process.
    readonly: no
    required: no
    minimum: 0
    maximum: 100
    default: 6
    mutable: no
    widget: spinner

  - identifier: mincontrast
    title: Minimum Contrast
    type: float
    description: >
      Used during analysis. 
      Below this contrast, a field is discarded.
    readonly: no
    required: no
    minimum: 0
    maximum: 1
    default: 0.3
    mutable: no
    widget: spinner

  - identifier: show
    title: Show
    type: integer
    description: >
      Used during analysis.
      0 = draw nothing
      1 or 2 = show fields and transforms
    readonly: no
    required: no
    minimum: 0
    maximum: 2
    default: 0
    mutable: no
    widget: spinner

  - identifier: tripod
    title: Tripod
    type: integer
    description: >
      Used during analysis and application.
      if 0, tripod mode is disabled.
      if > 0, specifies the frame to be used as a reference frame for tripod mode
      During application, relative and smoothing properties are both ignored if tripod mode is in use.
    readonly: no
    required: no
    minimum: 0
    maximum: 100000
    default: 0
    mutable: no
    widget: spinner

  - identifier: smoothing
    title: Smoothing
    type: integer
    description: >
      Used during application.
      Number of frames for lowpass filtering (2N + 1 frames)
    readonly: no
    required: no
    minimum: 0
    maximum: 100
    default: 15
    mutable: yes
    widget: spinner

  - identifier: maxshift
    title: Maxshift
    type: integer
    description: >
      Used during application.
      Maximum number of pixels to transform the image. -1 = no limit
    unit: pixels
    readonly: no
    required: no
    minimum: -1
    maximum: 1000
    default: -1
    mutable: yes
    widget: spinner

  - identifier: maxangle
    title: Maxangle
    type: float
    description: >
      Used during application.
      Maximum angle to rotate, -1 = no limit
    unit: radians
    readonly: no
    required: no
    minimum: -1
    maximum: 3.142
    default: -1
    mutable: yes
    widget: spinner

  - identifier: crop
    title: Crop
    type: boolean
    description: >
      Used during application.
      0 = keep border, 1 = black background
    readonly: no
    required: no
    default: 0
    mutable: yes

  - identifier: invert
    title: Invert
    type: boolean
    description: >
      Used during application.
      Invert transforms
    readonly: no
    required: no
    default: 0
    mutable: yes

  - identifier: relative
    title: Relative
    type: boolean
    description: >
      Used during application.
      Consider transforms as absolute (0) or relative (1)
    readonly: no
    required: no
    default: 1
    mutable: yes

  - identifier: zoom
    title: Zoom
    type: integer
    description: >
      Used during application.
      Additional zoom amount
    unit: percent
    readonly: no
    required: no
    minimum: -500
    maximum: 500
    default: 0
    mutable: yes
    widget: spinner

  - identifier: optzoom
    title: Optimal Zoom
    type: integer
    description: >
      Used during application.
      Automatically determine optimal zoom. 1 - static zoom, 2 - adaptive zoom
    readonly: no
    required: no
    minimum: 0
    maximum: 2
    default: 1
    mutable: yes
    widget: spinner

  - identifier: zoomspeed
    title: Optimal Zoom Speed
    type: float
    description: >
      Used during application.
      Zoom per frame (used when optzoom = 2)
    unit: percent
    readonly: no
    required: no
    minimum: 0
    maximum: 1
    default: 0.25
    mutable: yes
    widget: spinner

  - identifier: reload
    title: Reload Results
    description: >
      The application should set this to 1 when it updates the results
      property to indicate that the results should be reloaded.
    type: boolean
    mutable: yes

  - identifier: analyze
    title: Commence analysis
    description: >
      This is optional, but it can help applications avoid race conditions
      writing to the file. When not set, it does not affect the start of
      analysis. When set, analysis only starts and the file written if true.
    type: boolean
