.. index:: Grease Pencil Modifiers; Line Art Modifier
.. _bpy.types.GreasePencilLineartModifier:

*****************
Line Art Modifier
*****************

The *Line Art* modifier generates stylized Line Art from a scene, collection, or object.

In order for the effects of the modifier to be visible, the scene must have an active camera.
The generated lines are only generated on portions of the object that a visible from this camera.

.. note::

   Due to lack of global cache at the moment, each Line Art modifier will run the entire
   occlusion calculation for itself. So if you have multiple Line Art modifiers to select
   different parts of the scene (to apply different styles, etc.), the evaluation will take much longer.
   There are plans to remedy this in the future, but this is a known limitation for now.


Options
=======

.. figure:: /images/grease-pencil_modifiers_generate_line-art_panel.png
   :align: right

   The Line Art modifier.

.. _bpy.types.GreasePencilLineartModifier.use_cache:

Use Cache
   Optimize rendering by using cached scene data from the first Line Art modifier in the stack.
   This option has the disadvantage of certain settings becoming unavailable.

   This option is only available when you have more than one Line Art modifier
   in the same modifier stack and the modifier is not the first Line Art modifier in the stack.

Source Type
   Specifies the source from which Line Art generates strokes:

   :Scene: Uses all visible objects in the scene.
   :Collection: Uses only the objects within the chosen collection.
   :Object:
      Generates strokes from a single specified object.
      The following object types are supported:

      - :doc:`Mesh </modeling/meshes/index>`
      - :doc:`Text </modeling/texts/index>`
      - :doc:`Curve </modeling/curves/index>`
      - :doc:`Surface </modeling/surfaces/index>`
      - :doc:`Curves </modeling/curves_new/index>`

Object/Collection
   Based on the source type, collection or object can be selected as source geometry.

   .. _bpy.types.GreasePencilLineartModifier.use_invert_collection:

   Invert Collection Filtering
      Select everything except lines from specified collection.

.. note::

   Line Art will still load and calculate the entire visible scene to produce correct occlusion result,
   unless specified to do otherwise in object or collection Line Art *Usage* property.

Layer
   The Grease Pencil :ref:`bpy.types.GreasePencilLayer` to put the result in.

Material
   The Grease Pencil :ref:`bpy.types.MaterialGPencilStyle` to generate strokes with.

Line Radius
   The strokes generated by Line Art are given this radius.

Opacity
   The strokes generated by Line Art are given this Opacity.


Edge Types
----------

Line Art can identify different edge types. Selected edge types will be included in the result.

.. _bpy.types.GreasePencilLineartModifier.shadow_region_filtering:

Illumination Filtering
   Select feature lines that comes from lit or shaded regions.
   Will not affect cast shadow and light contour since they are at the border.

   :None: Not filtering any lines based on illumination region.
   :Illuminated: Only selecting lines from illuminated regions.
   :Shaded: Only selecting lines from shaded regions.
   :Illuminated (Enclosed Shapes):
      Selecting lines from lit regions, and make the combination of contour,
      light contour and shadow lines into enclosed shapes.

.. rubric:: Create

.. _bpy.types.GreasePencilLineartModifier.use_contour:
.. _bpy.types.GreasePencilLineartModifier.silhouette_filtering:
.. _bpy.types.GreasePencilLineartModifier.use_invert_silhouette:

Contour
   Generate strokes from contour lines.
   Where the edge becomes the separation line of front/backfacing faces.
   The silhouette can also be inverted by clicking the invert button.

   :Contour: Generate lines from contour.
   :Silhouette: Only generate lines from the silhouette of the source objects as a whole.
   :Individual Silhouette: Generate lines from the individual silhouettes of the source objects.

.. _bpy.types.GreasePencilLineartModifier.use_crease:

Crease
   Generate strokes where the edge angle is small enough.

   .. _bpy.types.GreasePencilLineartModifier.crease_threshold:

   Crease Threshold
      Angles smaller than this will be treated as creases.
      Crease angle priority: object Line Art crease override > Line Art default crease.

.. _bpy.types.GreasePencilLineartModifier.use_intersection:

Intersections
   Generate strokes where lines intersect between faces.

.. _bpy.types.GreasePencilLineartModifier.use_material:

Material Borders
   Generate strokes where the edge separates faces with different materials.

.. _bpy.types.GreasePencilLineartModifier.use_edge_mark:

Edge Marks
   Generate strokes from freestyle edge marks.

.. _bpy.types.GreasePencilLineartModifier.use_loose:

Loose
   Generate strokes for edges that do not form a :term:`Face`.

.. _bpy.types.GreasePencilLineartModifier.use_light_contour:

Light Contour
   Generate light/shadow separation lines from a reference
   :ref:`Light Object <bpy.types.GreasePencilLineartModifier.light_contour_object>`.

.. _bpy.types.GreasePencilLineartModifier.use_shadow:

Cast Shadow
   Project contour lines using a light source object.

.. rubric:: Options

.. _bpy.types.GreasePencilLineartModifier.use_overlap_edge_type_support:

Allow Overlapping Types
   Allow an edge to have multiple overlapping types.
   This will create a separate stroke for each overlapping type.


Light Reference
---------------

.. _bpy.types.GreasePencilLineartModifier.light_contour_object:

Light Object
   Use this light object to generate :ref:`Light Contour <bpy.types.GreasePencilLineartModifier.use_light_contour>`.

.. _bpy.types.GreasePencilLineartModifier.shadow_camera_size:

Shadow Camera Size
   This value represents the "Orthographic Scale" of an ortho camera.
   If the camera is put at the lamps position with this scale, it will represent the coverage of the shadow "camera".

.. _bpy.types.GreasePencilLineartModifier.shadow_camera_near:

Near
   Near clipping distance of shadow camera.

.. _bpy.types.GreasePencilLineartModifier.shadow_camera_far:

Far
   Far clipping distance of shadow camera


Geometry Processing
-------------------

.. _bpy.types.GreasePencilLineartModifier.source_camera:
.. _bpy.types.GreasePencilLineartModifier.use_custom_camera:

Custom Camera
   Use custom camera instead of the active camera for calculating strokes.
   Useful when baking multiple shots in different angles as well as for motion graphics effects.

Overlapping Edges as Contour
   This option allows overlapping edges (e.g. from an Edge Split modifier or imported geometry where
   two edges occupy the exact same space) to be drawn as contour. Enabling this option will slow down
   the calculation slightly but it will handle edge overlapping cases without erroneous occlusion results.

Instanced Objects
   This option enables particles and other instanced objects to be loaded for Line Art calculation.
   There will be performance impact when there are a large amount of instanced objects in the scene.

Clipping Boundaries
   When enabled, Line Art will generate clipping lines as contour type at the place
   where near or far clipping planes cut the model. Otherwise there will be no lines.

.. _bpy.types.GreasePencilLineartModifier.use_crease_on_smooth:

Crease on Smooth
   Allow crease edges to show inside smooth surfaces.

.. _bpy.types.GreasePencilLineartModifier.use_crease_on_sharp:

Crease on Sharp
   Allow creases to show on sharp edges.

.. _bpy.types.GreasePencilLineartModifier.use_back_face_culling:

Force Backface Culling
   Remove all back faces to speed up calculation.
   Note, removing back faces will create edges in different occlusion levels than when disabled.


Occlusion
---------

.. figure:: /images/grease-pencil_modifiers_generate_line-art_occlusion-panel.png
   :align: right

   Occlusion subpanel.

Range
   If enabled, the modifier will select lines that have an occlusion level between start and end values.

Level
   Desired occlusion level to be selected as Line Art result. A value of 0 means visible lines (no occlusion).
   A value of 1 means selecting lines that have been occluded by exactly one layer of faces.


Material Mask
^^^^^^^^^^^^^

If enabled, Line Art will only select lines that are occluded by certain faces whose material
have specific occlusion masks set.

Masks
   To select edges that have been occluded by the selected
   :ref:`Material Mask <bpy.types.MaterialLineArt.use_material_mask_bits>`.

Exact Match
   If enabled, only lines that are occluded with the exact mask bit combination will be selected.
   Otherwise, lines that have been occluded by any one of specified material masks will be selected.

.. figure:: /images/grease-pencil_modifiers_generate_line-art_transparency-mask.png
   :align: right

   Demonstration of the usage of material masks.


Intersection
------------

Allows you to select edges that intersect between two collections.

.. _bpy.types.GreasePencilLineartModifier.use_intersection_mask:

Collection Mask
   Mask bits to match from :ref:`Collection Line Art <bpy.types.Collection.lineart_intersection_mask>` properties.

.. _bpy.types.GreasePencilLineartModifier.use_intersection_match:

Exact Match
   Require matching all intersection masks instead of just one.

.. figure:: /images/grease-pencil_modifiers_generate_line-art_collection-mask.png

   Demonstration of the usage of collection masks.


.. _bpy.types.GreasePencilLineartModifier.use_face_mark:

Face Mark Filtering
-------------------

.. figure:: /images/grease-pencil_modifiers_generate_line-art_face-mark-filtering-panel.png
   :align: right

   Face Mark Filtering subpanel.

*Face Mark Filtering* can be used to have manual control over which
feature edges produce strokes by using Freestyle face marks.

.. _bpy.types.GreasePencilLineartModifier.use_face_mark_invert:

Invert
   Invert face mark filtering.

.. _bpy.types.GreasePencilLineartModifier.use_face_mark_boundaries:

Boundaries
   Filter feature lines based on face mark boundaries.

.. _bpy.types.GreasePencilLineartModifier.use_face_mark_keep_contour:

Keep Contour
   Preserve contour lines while filtering.

.. figure:: /images/grease-pencil_modifiers_generate_line-art_face-mark-filtering-example.png


Chaining
--------

.. figure:: /images/grease-pencil_modifiers_generate_line-art_chaining-panel.png
   :align: right

   Chaining subpanel.

Chain
   Intersection with Contour
      Allows intersection lines to be chained together with contour lines.

      .. note::

         Enabling this option will lead to ambiguity in intersection edge types.
         Intersection lines that have not been able to chain with any nearby contour lines will remain
         as intersection lines.

   All Lines
      Enabling this option will cause all lines to have the type of contour and to be chained together.

   Loose Edges
      Allow floating Edges that do not form a face to be chained together.

   Loose Edges as Contour
      Edges that do not form a face will be classified as contour lines.

   Preserve Details
      Instead of splitting at each occlusion change, keep small details from the initial chain.
      When details are not kept, will create a much smoother result.

   Geometry Space
      Use geometry distance for chaining instead of image space.

Image Threshold
   Allow the end point of short segments to be chained together if the 2D image space distance
   between them are within the specified threshold.

.. _bpy.types.GreasePencilLineartModifier.smooth_tolerance:

Smooth Tolerance
   The strength of smoothing applied on jagged chains.

Angle Splitting
   Split a chain at sharp "turning" points specified by this angle.


Vertex Weight Transfer
----------------------

.. figure:: /images/grease-pencil_modifiers_generate_line-art_vertex-weight-panel.png
   :align: right

   Vertex Weight Transfer subpanel.

Filter Source
   If source mesh has vertex groups whose name starts with this text, then the vertex weight info
   will be transferred into weight groups in Grease Pencil strokes.

Match Output
   Transfer the filtered object vertex weights into Grease Pencil weight groups with the same names
   as the filtered ones.

Target
   If *Match Output* is off, then a target vertex group has to be specified.
   If there are multiple weight groups copied into target, then the highest weight value is copied into it.


Composition
-----------

.. figure:: /images/grease-pencil_modifiers_generate_line-art_composition-panel.png
   :align: right

   Composition subpanel.

.. _bpy.types.GreasePencilLineartModifier.overscan:

Overscan
   To optimize rendering, Blender only renders the strokes for edges of the object that are in the camera's view.
   This optimization however, can result in strokes ending abruptly at the edge of the image.

   This value prevents this error by adding a margin outside the camera's view to continue computing strokes.

.. _bpy.types.GreasePencilLineartModifier.use_image_boundary_trimming:

Image Boundary Trimming
   Trim all stroke right at the boundary of image (including overscan region).

.. _bpy.types.GreasePencilLineartModifier.stroke_depth_offset:

Depth Offset
   Move strokes slightly towards the camera to avoid clipping while preserve depth for the viewport.
   This option is unavailable unless :ref:`Show in Front <bpy.types.Object.show_in_front>` is disabled.

.. _bpy.types.GreasePencilLineartModifier.use_offset_towards_custom_camera:

Towards Custom Camera
   Offset strokes towards selected camera (see *Custom Camera* above) instead of the active camera.


Bake
----

.. figure:: /images/grease-pencil_modifiers_generate_line-art_baking-panel.png
   :align: right

   Bake options.

Bake Line Art
   Bakes Line Art strokes for active Grease Pencil object within the *start*, *end* frame range in scene.
   After baking, baked Line Art modifiers will be deactivated automatically.

Bake All
   Bakes all Grease Pencil objects that contains at least one Line Art modifier.
   After baking, baked Line Art modifiers will be deactivated automatically.

Clear Baked Line Art
   Clears baked Line Art frames within the scene frame range for active Grease Pencil object.

Clear All
   Clears baked Line Art for all Grease Pencil objects that
   contains at least one Line Art modifier.

   .. warning::

      If you have drawn anything manually in the frame range of where Line Art runs,
      this operation will also clear those strokes!

Continue without Clearing
   Re-activate a specific Line Art modifier without clearing baked strokes. This is useful for working
   on multiple portions of frames separately.
