Convert Functions

class pyonfx.convert.Pixel(x, y, alpha)

alpha: Alias for field number 2

x: Alias for field number 0

y: Alias for field number 1

class pyonfx.convert.ColorModel(value)[source]: An enumeration.

class pyonfx.convert.Convert[source]

This class is a collection of static methods that will help the user to convert everything needed to the ASS format.

static time(ass_ms)[source]

Converts between milliseconds and ASS timestamp.

You can probably ignore that function, you will not make use of it for KFX or typesetting generation.

Parameters: ass_ms (int or str) – If int, than milliseconds are expected, else ASS timestamp as str is expected.
Returns: If milliseconds -> ASS timestamp, else if ASS timestamp -> milliseconds, else ValueError will be raised.

static ms_to_frames(ms, fps, is_start)[source]

Converts from milliseconds to frames.

Parameters

ms (int) – Milliseconds.
fps (positive int, float or Fraction) – Frames per second.
is_start (bool) – True if this time will be used for the start_time of a line, else False.

Returns

The output represents ms converted.

static frames_to_ms(frames, fps, is_start)[source]

Converts from frames to milliseconds.

Parameters

frames (int) – Frames.
fps (positive int, float or Fraction) – Frames per second.
is_start (bool) – True if this time will be used for the start_time of a line, else False.

Returns

The output represents frames converted.

static move_ms_to_frame(ms, fps, is_start)[source]

Moves the ms to when the corresponding frame starts or ends (depending on is_start). It is something close to using “CTRL + 3” and “CTRL + 4” on Aegisub 3.2.2.

Parameters

ms (int) – Milliseconds.
fps (positive int, float or Fraction) – Frames per second.
is_start (bool) – True if this time will be used for the start_time of a line, else False.

Returns

The output represents ms converted.

static alpha_ass_to_dec(alpha_ass)[source]

Converts from ASS alpha string to corresponding decimal value.

Parameters: alpha_ass (str) – A string in the format ‘&HXX&’.
Returns: A decimal in [0, 255] representing alpha_ass converted.

Examples

print(Convert.alpha_ass_to_dec("&HFF&"))

>>> 255

static alpha_dec_to_ass(alpha_dec)[source]

Converts from decimal value to corresponding ASS alpha string.

Parameters: alpha_dec (int or float) – Decimal in [0, 255] representing an alpha value.
Returns: A string in the format ‘&HXX&’ representing alpha_dec converted.

Examples

print(Convert.alpha_dec_to_ass(255))
print(Convert.alpha_dec_to_ass(255.0))

>>> "&HFF&"
>>> "&HFF&"

static color(c, input_format, output_format, round_output=True)[source]

Converts a provided color from a color model to another.

Parameters

c (str or tuple of int or tuple of float) – A color in the format input_format.
input_format (ColorModel) – The color format of c.
output_format (ColorModel) – The color format for the output.
round_output (bool) – A boolean to determine whether the output should be rounded or not.

Returns

A color in the format output_format.

Examples

print(Convert.color("&H0000FF&", ColorModel.ASS, ColorModel.RGB))

>>> (255, 0, 0)

static color_ass_to_rgb(color_ass, as_str=False)[source]

Converts from ASS color string to corresponding RGB color.

Parameters

color_ass (str) – A string in the format ‘&HBBGGRR&’.
as_str (bool) – A boolean to determine the output type format.

Returns

The output represents color_ass converted. If as_str = False, the output is a tuple of integers in range [0, 255]. Else, the output is a string in the format ‘#RRGGBB’.

Examples

print(Convert.color_ass_to_rgb("&HABCDEF&"))
print(Convert.color_ass_to_rgb("&HABCDEF&", as_str=True))

>>> (239, 205, 171)
>>> "#EFCDAB"

static color_ass_to_hsv(color_ass, round_output=True)[source]

Converts from ASS color string to corresponding HSV color.

Parameters

color_ass (str) – A string in the format ‘&HBBGGRR&’.
round_output (bool) – A boolean to determine whether the output should be rounded or not.

Returns

The output represents color_ass converted. If round_output = True, the output is a tuple of integers in range ( [0, 360), [0, 100], [0, 100] ). Else, the output is a tuple of floats in range ( [0, 360), [0, 100], [0, 100] ).

Examples

print(Convert.color_ass_to_hsv("&HABCDEF&"))
print(Convert.color_ass_to_hsv("&HABCDEF&", round_output=False))

>>> (30, 28, 94)
>>> (30.000000000000014, 28.451882845188294, 93.72549019607843)

static color_rgb_to_ass(color_rgb)[source]

Converts from RGB color to corresponding ASS color.

Parameters: color_rgb (str or tuple of int or tuple of float) – Either a string in the format ‘#RRGGBB’ or a tuple of three integers (or floats) in the range [0, 255].
Returns: A string in the format ‘&HBBGGRR&’ representing color_rgb converted.

Examples

print(Convert.color_rgb_to_ass("#ABCDEF"))

>>> "&HEFCDAB&"

static color_rgb_to_hsv(color_rgb, round_output=True)[source]

Converts from RGB color to corresponding HSV color.

Parameters

color_rgb (str or tuple of int or tuple of float) – Either a string in the format ‘#RRGGBB’ or a tuple of three integers (or floats) in the range [0, 255].
round_output (bool) – A boolean to determine whether the output should be rounded or not.

Returns

The output represents color_rgb converted. If round_output = True, the output is a tuple of integers in range ( [0, 360), [0, 100], [0, 100] ). Else, the output is a tuple of floats in range ( [0, 360), [0, 100], [0, 100] ).

Examples

print(Convert.color_rgb_to_hsv("#ABCDEF"))
print(Convert.color_rgb_to_hsv("#ABCDEF"), round_output=False)

>>> (210, 28, 94)
>>> (210.0, 28.451882845188294, 93.72549019607843)

static color_hsv_to_ass(color_hsv)[source]

Converts from HSV color string to corresponding ASS color.

Parameters: color_hsv (tuple of int/float) – A tuple of three integers (or floats) in the range ( [0, 360), [0, 100], [0, 100] ).
Returns: A string in the format ‘&HBBGGRR&’ representing color_hsv converted.

Examples

print(Convert.color_hsv_to_ass((100, 100, 100)))

>>> "&H00FF55&"

static color_hsv_to_rgb(color_hsv, as_str=False, round_output=True)[source]

Converts from HSV color string to corresponding RGB color.

Parameters

color_hsv (tuple of int/float) – A tuple of three integers (or floats) in the range ( [0, 360), [0, 100], [0, 100] ).
as_str (bool) – A boolean to determine the output type format.
round_output (bool) – A boolean to determine whether the output should be rounded or not.

Returns

The output represents color_hsv converted. If as_str = False, the output is a tuple ( also, if round_output = True, the output is a tuple of integers in range ( [0, 360), [0, 100], [0, 100] ), else a tuple of float in range ( [0, 360), [0, 100], [0, 100] ) ). Else, the output is a string in the format ‘#RRGGBB’.

Examples

print(Convert.color_hsv_to_rgb((100, 100, 100)))
print(Convert.color_hsv_to_rgb((100, 100, 100), as_str=True))
print(Convert.color_hsv_to_rgb((100, 100, 100), round_output=False))

>>> (85, 255, 0)
>>> "#55FF00"
>>> (84.99999999999999, 255.0, 0.0)

static text_to_shape(obj, fscx=None, fscy=None)[source]

Converts text with given style information to an ASS shape.

Tips: You can easily create impressive deforming effects.

Parameters

obj (Line, Word, Syllable or Char) – An object of class Line, Word, Syllable or Char.
fscx (float, optional) – The scale_x value for the shape.
fscy (float, optional) – The scale_y value for the shape.

Returns

A Shape object, representing the text with the style format values of the object.

Examples

line = Line.copy(lines[1])
line.text = "{\\an7\\pos(%.3f,%.3f)\\p1}%s" % (line.left, line.top, Convert.text_to_shape(line))
io.write_line(line)

static text_to_clip(obj, an=5, fscx=None, fscy=None)[source]

Converts text with given style information to an ASS shape, applying some translation/scaling to it since it is not possible to position a shape with pos() once it is in a clip.

This is an high level function since it does some additional operations, check text_to_shape for further infromations.

Tips: You can easily create text masks even for growing/shrinking text without too much effort.

Parameters

obj (Line, Word, Syllable or Char) – An object of class Line, Word, Syllable or Char.
an (integer, optional) – The alignment wanted for the shape.
fscx (float, optional) – The scale_x value for the shape.
fscy (float, optional) – The scale_y value for the shape.

Returns

A Shape object, representing the text with the style format values of the object.

Examples

line = Line.copy(lines[1])
line.text = "{\\an5\\pos(%.3f,%.3f)\\clip(%s)}%s" % (line.center, line.middle, Convert.text_to_clip(line), line.text)
io.write_line(line)

static text_to_pixels(obj, supersampling=8)[source]

Converts text with given style information to a list of pixel data.

A pixel data is a dictionary containing ‘x’ (horizontal position), ‘y’ (vertical position) and ‘alpha’ (alpha/transparency).

It is highly suggested to create a dedicated style for pixels, because you will write less tags for line in your pixels, which means less size for your .ass file.

The style suggested (named “p” in the example) is:
- an=7 (very important!);
- bord=0;
- shad=0;
- For Font informations leave whatever the default is;

Tips: It allows easy creation of text decaying or light effects.

Parameters

obj (Line, Word, Syllable or Char) – An object of class Line, Word, Syllable or Char.
supersampling (int) – Value used for supersampling. Higher value means smoother and more precise anti-aliasing (and more computational time for generation).

Returns

A list of dictionaries representing each individual pixel of the input text styled.

Examples

l.style = "p"
p_sh = Shape.rectangle()
for pixel in Convert.text_to_pixels(l):
    x, y = math.floor(l.left) + pixel.x, math.floor(l.top) + pixel.y
    alpha = "\alpha" + Convert.alpha_dec_to_ass(pixel.alpha) if pixel.alpha != 0 else ""

    l.text = "{\p1\pos(%d,%d)%s}%s" % (x, y, alpha, p_sh)
    io.write_line(l)

static shape_to_pixels(shape, supersampling=8)[source]

Converts a Shape object to a list of pixel data.

A pixel data is a dictionary containing ‘x’ (horizontal position), ‘y’ (vertical position) and ‘alpha’ (alpha/transparency).

It is highly suggested to create a dedicated style for pixels, because you will write less tags for line in your pixels, which means less size for your .ass file.

The style suggested (named “p” in the example) is:
- an=7 (very important!);
- bord=0;
- shad=0;
- For Font informations leave whatever the default is;

Tips: As for text, even shapes can decay!

Parameters

shape (Shape) – An object of class Shape.
supersampling (int) – Value used for supersampling. Higher value means smoother and more precise anti-aliasing (and more computational time for generation).

Returns

A list of dictionaries representing each individual pixel of the input shape.

Examples

l.style = "p"
p_sh = Shape.rectangle()
for pixel in Convert.shape_to_pixels(Shape.heart(100)):
    x, y = math.floor(l.left) + pixel.x, math.floor(l.top) + pixel.y
    alpha = "\alpha" + Convert.alpha_dec_to_ass(pixel.alpha) if pixel.alpha != 0 else ""

    l.text = "{\p1\pos(%d,%d)%s}%s" % (x, y, alpha, p_sh)
    io.write_line(l)