Crop

From Avisynth wiki
(Difference between revisions)
Jump to: navigation, search
m (1 revision)
(add link to avs+ documentation)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
{{Template:Func3Def|Crop(clip ''clip'', int ''left'', int ''top'', int ''width'', int ''height'', bool ''align'')|Crop(clip ''clip'', int ''left'', int ''top'', int ''-right'', int ''-bottom'', bool ''align'')|CropBottom(clip ''clip'', int ''count'')}}
+
<div {{BlueBox2|40|0|3px solid purple}} >
 +
{{AvsPlusFullname}}<br>
 +
Up-to-date documentation: [https://avisynthplus.readthedocs.io/en/latest/avisynthdoc/corefilters/crop.html https://avisynthplus.readthedocs.io]
 +
</div>
  
−
So if you have a 640x480 video, and you want to crop 8 off the left, 2 off the top, 9 off the right, and 4 off the bottom, you would use this:
 
  
−
Crop(8,2,-9,-4)
+
''Cropping'' refers to the removal of the outer parts of an image to improve framing, changing the framesize (also called image or storage aspect ratio). See Wikipedia: [[Wikipedia:Cropping_(image)|Cropping]].
 +
__TOC__
 +
== Syntax and Parameters ==
 +
<div style="max-width:50em" >
 +
{{Func3Def
 +
|Crop(clip ''clip'', int ''left'', int ''top'', int ''width'', int ''height'' [, bool ''align'' ] )
 +
|Crop(clip ''clip'', int ''left'', int ''top'', int ''-right'', int ''-bottom'' [, bool ''align'' ] )
 +
|CropBottom(clip ''clip'', int ''count'')
 +
}}
  
−
Crop crops excess pixels off of each frame. If your source video has 720x480 resolution, and you want to reduce it to 352x240 for VideoCD, here's the correct way to do it:  
+
:{{Par2|left, top|int|}}
 +
::Cropping of the {{FuncArg|left}} and {{FuncArg|top}} edges respectively, in pixels.
 +
::*See [[#Crop restrictions|crop modulo restrictions]] below.
  
−
# Converts CCIR601 to VCD, preserving the correct aspect ratio:
+
:{{Par2|width, height|int|}}
−
ReduceBy2()
+
:{{Par2|right, bottom|int|}}
−
Crop(4, 0, 352, 240)
+
<div {{ListItemContinue|4}} >
 +
The third and fourth arguments have different names or ''aliases'', depending on their value:
 +
*If &nbsp;&gt; zero, these set the {{FuncArg|width}} and {{FuncArg|height}} of the resulting clip.
 +
*If &lt;= zero, they set the cropping of the {{FuncArg|right}} and {{FuncArg|bottom}} edges respectively.
 +
Note, there are certain limits:
 +
* {{FuncArg|clip}}.[[Clip_properties|Width]] must be &gt;= ({{FuncArg|left}} + {{FuncArg|width}})
 +
* {{FuncArg|clip}}.[[Clip_properties|Width]] must be &gt;&nbsp; ({{FuncArg|left}} + {{FuncArg|right}})
 +
* {{FuncArg|clip}}.[[Clip_properties|Height]] must be &gt;= ({{FuncArg|top}} + {{FuncArg|height}})
 +
* {{FuncArg|clip}}.[[Clip_properties|Height]] must be &gt;&nbsp; ({{FuncArg|top}} + {{FuncArg|bottom}})
 +
&nbsp;...otherwise it would enlarge ("un-crop") the clip, or reduce width or height to 0,
 +
which is not allowed.
 +
*See [[#Crop restrictions|crop modulo restrictions]] below.
 +
</div>
  
−
In AviSynth v2.01 and later, the alternative syntax using negative (or zero) values is possible. In this case, the last two parameters are also treated as offsets, VirtualDub-style. For example:
+
:{{Par2|count|int|}}
 +
::The alternative '''CropBottom''' syntax was created to crop garbage off the bottom of a clip captured from [[Wikipedia:VHS|VHS]] tape. It removes {{FuncArg|count}} lines from the bottom of the frame.  
 +
::*See [[#Crop restrictions|crop modulo restrictions]] below.
  
−
# Crops 16 pixels all the way around the picture, regardless of image size:
+
:{{Par2|align|bool|false}}
−
Crop(16, 16, -16, -16)
+
::Cropping an YUY2/RGB32 image is always [[Modulo|mod4]] (four bytes). However, when reading ''x'' bytes (an int), it is faster when the read is aligned to a mod''x'' placement in memory. MMX/SSE likes 8-byte alignment and SSE2 likes 16-byte alignment. If the data is NOT aligned, each read/write operation will be delayed at least 4 cycles. So images are always aligned to mod16 when they are created by AviSynth.
  
−
The alternative CropBottom syntax is useful for cropping garbage off the bottom of a clip captured from VHS tape. It removes ''count'' lines from the bottom of each frame.  
+
::If an image has been cropped, they will sometimes be placed unaligned in memory; {{FuncArg|align}}=''true'' will copy the entire frame from the unaligned memory placement to an aligned one.  
  
−
== Memory alignment ==
+
::'''So if the penalty of the following filter is larger than the penalty of a complete image copy, using {{FuncArg|align}}=''true'' will be faster''' &ndash; especially when it is followed by smoothers.
−
In v2.53 an option ''align'' (false by default) is added:
+
  
−
Cropping an YUY2/RGB32 image is always mod4 (four bytes). However, when reading x bytes (an int), it is faster when the read is aligned to a modx placement in memory. MMX/SSE likes 8-byte alignment and SSE2 likes 16-byte alignment. If the data is NOT aligned, each read/write operation will be delayed at least 4 cycles. So images are always aligned to mod16 when they are created by AviSynth.
+
</div>
−
 
+
−
If an image has been cropped, they will sometimes be placed unaligned in memory - "align = true" will copy the entire frame from the unaligned memory placement to an aligned one. So if the penalty of the following filter is larger than the penalty of a complete image copy, using "align=true" will be faster. Especially when it is followed by smoothers.
+
  
 
== Crop restrictions ==
 
== Crop restrictions ==
−
In order to preserve the data structure of the different colorspaces, the following mods should be used. You will not get an error message if they are not obeyed, but it may create strange artifacts. For a complete discussion on this, see DataStorageInAviSynth ...
+
<div style="max-width:48em" >
 +
:In order to preserve the data structure of the different colorspaces, the following [[Modulo|mods]] should be used. You will not get an error message if they are not obeyed, but you may get strange artifacts. For a complete discussion on this, see [[Filter_SDK/Data_storage]]
  
−
{| border="1" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;"
+
::{| border="1" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse;"
 
|-
 
|-
 
! rowspan=2 | Colorspace
 
! rowspan=2 | Colorspace
Line 51: Line 75:
 
| mod-2
 
| mod-2
 
| mod-4
 
| mod-4
 +
|-
 +
| YV411
 +
| mod-4
 +
| ''no restriction''
 +
| mod-2
 +
|-
 +
| YV16
 +
| mod-2
 +
| ''no restriction''
 +
| mod-2
 +
|-
 +
| YV24
 +
| ''no restriction''
 +
| ''no restriction''
 +
| mod-2
 
|-
 
|-
 
|}
 
|}
  
−
'''Note:''' The [[Resize|resize functions]] optionally allow fractional cropping of the input frame. This results in a weighting being applied to the edge pixels being resized. These options may be used if the mod-n format dimension restriction of crop are inconvienient. In summary: “For cropping off hard artifacts like VHS head noise or letterbox borders always use Crop. For extracting a portion of an image and to maintain accurate edge resampling use the resize cropping parameters.” ([http://forum.doom9.org/showthread.php?s=&threadid=91630 Doom9 thread])
+
:'''Note:''' The [[Resize|resize functions]] allow fractional (sub-pixel) cropping of the frame, with a weighting being applied to the edge pixels being resized. This may be used if the mod-''n'' format dimension restriction of '''Crop''' are inconvenient.  
 +
 
 +
:In summary: ''For cropping off hard artifacts like VHS head noise or letterbox borders always use '''''Crop'''''. For extracting a portion of an image and to maintain accurate edge resampling, use the '''''Resize''''' cropping parameters.'' ([http://forum.doom9.org/showthread.php?s=&threadid=91630 Doom9 thread])
 +
</div>
 +
 
 +
== Examples ==
 +
*If your source video has 720x480 resolution, and you want to reduce it to 352x240 for [[Wikipedia:Video_CD|VideoCD]], here's the correct way to do it:
 +
<div {{BoxWidthIndent|56|2}} >
 +
# Converts CCIR601 to VCD, preserving the correct aspect ratio
 +
[[ReduceBy2]]
 +
Crop(4, 0, 352, 240)
 +
</div>
 +
 
 +
*Using the alternative syntax with negative (or zero) values in the last two parameters, they become ''offsets'', [[VirtualDub]]-style:
 +
<div {{BoxWidthIndent|56|2}} >
 +
# Crops 16 pixels all the way around the picture, regardless of image size
 +
Crop(16, 16, -16, -16)
 +
 +
# crop 8 off the left, 2 off the top, 9 off the right, and 4 off the bottom
 +
Crop(8, 2, -9, -4)
 +
</div>
 +
 
 +
== Changes ==
 +
{| border="1"
 +
|-
 +
| v2.53
 +
| Added align option.
 +
|}
  
 
[[Category:Internal filters]]
 
[[Category:Internal filters]]
 +
[[Category:Borders_and_Cropping]]

Latest revision as of 03:54, 18 September 2022

AviSynth+
Up-to-date documentation: https://avisynthplus.readthedocs.io


Cropping refers to the removal of the outer parts of an image to improve framing, changing the framesize (also called image or storage aspect ratio). See Wikipedia: Cropping.

Contents

[edit] Syntax and Parameters

Crop(clip clip, int left, int top, int width, int height [, bool align ] )
Crop(clip clip, int left, int top, int -right, int -bottom [, bool align ] )
CropBottom(clip clip, int count)

int  left, top =
Cropping of the left and top edges respectively, in pixels.
int  width, height =
int  right, bottom =

The third and fourth arguments have different names or aliases, depending on their value:

  • If  > zero, these set the width and height of the resulting clip.
  • If <= zero, they set the cropping of the right and bottom edges respectively.

Note, there are certain limits:

  • clip.Width must be >= (left + width)
  • clip.Width must be >  (left + right)
  • clip.Height must be >= (top + height)
  • clip.Height must be >  (top + bottom)

 ...otherwise it would enlarge ("un-crop") the clip, or reduce width or height to 0, which is not allowed.

int  count =
The alternative CropBottom syntax was created to crop garbage off the bottom of a clip captured from VHS tape. It removes count lines from the bottom of the frame.
bool  align = false
Cropping an YUY2/RGB32 image is always mod4 (four bytes). However, when reading x bytes (an int), it is faster when the read is aligned to a modx placement in memory. MMX/SSE likes 8-byte alignment and SSE2 likes 16-byte alignment. If the data is NOT aligned, each read/write operation will be delayed at least 4 cycles. So images are always aligned to mod16 when they are created by AviSynth.
If an image has been cropped, they will sometimes be placed unaligned in memory; align=true will copy the entire frame from the unaligned memory placement to an aligned one.
So if the penalty of the following filter is larger than the penalty of a complete image copy, using align=true will be faster – especially when it is followed by smoothers.

[edit] Crop restrictions

In order to preserve the data structure of the different colorspaces, the following mods should be used. You will not get an error message if they are not obeyed, but you may get strange artifacts. For a complete discussion on this, see Filter_SDK/Data_storage
Colorspace Width Height
progressive video interlaced video
RGB no restriction no restriction mod-2
YUY2 mod-2 no restriction mod-2
YV12 mod-2 mod-2 mod-4
YV411 mod-4 no restriction mod-2
YV16 mod-2 no restriction mod-2
YV24 no restriction no restriction mod-2
Note: The resize functions allow fractional (sub-pixel) cropping of the frame, with a weighting being applied to the edge pixels being resized. This may be used if the mod-n format dimension restriction of Crop are inconvenient.
In summary: For cropping off hard artifacts like VHS head noise or letterbox borders always use Crop. For extracting a portion of an image and to maintain accurate edge resampling, use the Resize cropping parameters. (Doom9 thread)

[edit] Examples

  • If your source video has 720x480 resolution, and you want to reduce it to 352x240 for VideoCD, here's the correct way to do it: 
# Converts CCIR601 to VCD, preserving the correct aspect ratio
ReduceBy2
Crop(4, 0, 352, 240)
  • Using the alternative syntax with negative (or zero) values in the last two parameters, they become offsets, VirtualDub-style: 
# Crops 16 pixels all the way around the picture, regardless of image size
Crop(16, 16, -16, -16)

# crop 8 off the left, 2 off the top, 9 off the right, and 4 off the bottom
Crop(8, 2, -9, -4)

[edit] Changes

v2.53 Added align option.
Retrieved from "http://avisynth.nl/index.php?title=Crop&oldid=12741"
Personal tools