Python API
==========

The two main entry points mirror the :ref:`render <cli-render>` and :ref:`video <cli-video>` CLI commands
and take the same configuration objects.

.. code-block:: python
  :linenos:

  from pathlib import Path
  from svgsequencevideo import RenderConfig, renderSvg

  renderSvg(Path("drawing.svg"), RenderConfig(outputDir=Path("build"), width=1920))

.. code-block:: python
  :linenos:

  from svgsequencevideo import ProjectConfig, VideoConfig, buildVideo

  config = ProjectConfig(video=VideoConfig(revealDuration=15.0, weights={"Foreground": 2.0}))
  buildVideo(config)

Configuration
-------------

.. autoclass:: svgsequencevideo.RenderConfig
   :members:
   :exclude-members: resolve, getResolvedDimensions, getResolvedInkscapePath

.. autoclass:: svgsequencevideo.VideoConfig
   :members:
   :exclude-members: resolve, getResolvedWeights, getResolvedFfmpegPath

.. autoclass:: svgsequencevideo.ProjectConfig
   :members:

Rendering
---------

.. autofunction:: svgsequencevideo.renderSvg

Video
-----

.. autofunction:: svgsequencevideo.buildVideo

Custom heuristics
------------------

The reveal timing of each element is driven by a :class:`~svgsequencevideo.Heuristic`.
Subclass it and pass an instance to :func:`~svgsequencevideo.buildVideo` to
use your own logic instead of the built-in ``equal``/``area``/``complex``
ones.

.. code-block:: python
  :linenos:

  from svgsequencevideo import Heuristic, buildVideo

  class MyHeuristic(Heuristic):
      def computeBaseFactor(self, node, context):
          return node.objectCount # every element gets the same reveal time

  buildVideo(config, heuristic=MyHeuristic())

.. autoclass:: svgsequencevideo.Heuristic
   :members: computeBaseFactor, computeFactor
   :undoc-members:

Exceptions
----------

.. autoexception:: svgsequencevideo.config.InvalidRenderConfigError

.. autoexception:: svgsequencevideo.render.RenderOutputConflictError

.. autoexception:: svgsequencevideo.render.ResumeMismatchError

.. autoexception:: svgsequencevideo.heuristic.CacheNotFoundError