Package: image-pattern
image_pattern - package for creating image templates andgeneration of images from these templates using changing content.What’s all this for?It is often necessary to generate the same type of images with changing content.For example, images to be shared to social networks or to create a user avatar with the name(if no picture for the avatar is specified).I wanted to have a declarative way to describe image templates, and simple generation of images from them.I hope I made it.Installationshell script pip3 installimage-patternLet’s startFirst we need to create the pattern. We’ll create an image pattern of the avatar.The image pattern is defined with thePatternas follows:fromimage_patternimportPatternclassAvatar(Pattern):passEach image pattern consists of two components:canvas - the image canvas settings, such as size;layers - layers that contain image content;fromimage_patternimport(Pattern,Canvas,)classAvatar(Pattern):canvas=Canvas(size=(200,200))In this case we created an empty pattern for 200x200 image.Now, we can generate an image from it with the code:avatar_pattern=Avatar()image=avatar_pattern.render()image.save('avatar.jpg','JPEG')And we get the next image:Now we need to set content.We’ll start by adding the first layer:from__future__importannotationsfromtypingimportListfromimage_patternimport(Pattern,Canvas,Layer,Rectangle,Point,)classAvatar(Pattern):canvas=Canvas(size=(200,200),)layers:List[Layer]=[Layer(Rectangle(size=(100,200),point=Point(x=0,y=0),background_color=(51,204,255),),Rectangle(size=(100,200),point=Point(x=100,y=0),background_color=(255,51,153),),),]avatar_pattern=Avatar()image=avatar_pattern.render()image.save('avatar.jpg','JPEG')Let’s run the script and get the image:What’s going on here:We added a list of layers that contains one layer.This layer contains two rectangles;Thesizeproperty specifies the size of the rectangle in pixels;Thepointproperty specifies a point on the canvas indicating the
upper left corner of the element;Thebackground_colorproperty specifies the color of the
rectangle in theRGBsystem.More information about the elements and their properties can be found inAPI.After reviewing this example, a reasonable question may arise: Why do we need layers?So that no overlapping of elements occurs within one layer.For example, if we move the right rectangle by 50 pixels to the left inside one layer to make it run over the left rectangle:...Layer(Rectangle(size=(100,200),point=Point(x=0,y=0),background_color=(51,204,255),),Rectangle(size=(100,200),point=Point(x=50,y=0),background_color=(255,51,153),),),...we’ll generate the next image:As we can see, the right rectangle is missing from the image.If we increase the height of the image, we can see where it disappeared:...classAvatar(Pattern):canvas=Canvas(size=(200,400),)...As we can see, the right rectangle has shifted to down so as not to intersect with the left rectangle in the same layer.The rule of shifting elements is very simple - elements are always shifted down.This is especially useful for working with texts. When the length of text is unknown.But if we return the height of 200 pixels and place the rectangles in
different layers:...layers:List[Layer]=[Layer(Rectangle(size=(100,200),point=Point(x=0,y=0),background_color=(51,204,255),),),Layer(Rectangle(size=(100,200),point=Point(x=50,y=0),background_color=(255,51,153),),),]...then we can generate the next image:As we can see, the rectangles are superimposed on each other.That’s because the layers serve to specificallyto put elements on top of each other.Okay, now we need to write a text in our imageFor this we will need a text element and a new layer:...Layer(Text(text='Image Pattern',font=FONT_PATH,font_color=(255,255,255),font_size=42,point=Point(x=0,y=0),margin=Position(top=20,left=20,right=20,),)),...You can read more about the element in theAPIsection.By running the script, we get the image:Template takes into account the transfer of text by words, if there is not enough space for the text.We can also specify fonts, alignment and indents.Let’s put the first letters of words in the center of the image:...fromimage_patternimport(...HorizontalAlignment,VerticalAlignment,)...Layer(Text(text='IP',font=FONT_PATH,font_color=(255,255,255),font_size=102,point=Point(x=100,y=100),margin=Position(left=20,right=20,),horizontal_alignment=HorizontalAlignment.CENTER,vertical_alignment=VerticalAlignment.CENTER,),),...We got the image:Hmm… We have the feeling that the text is not in center of the image.However, that’s not entirely true. This is because the image template is used to align the width of the entire line.And since the width of the letterIis less than the width of the letterP, the text looks as if shifted.To get rid of this effect, we will try to place each letter in the
center of its rectangle as follows....Text(text='I',font=FONT_PATH,font_color=(255,255,255),font_size=102,point=Point(x=50,y=100),margin=Position(left=20,right=20,),horizontal_alignment=HorizontalAlignment.CENTER,vertical_alignment=VerticalAlignment.CENTER,),Text(text='P',font=FONT_PATH,font_color=(255,255,255),font_size=102,point=Point(x=150,y=100),margin=Position(left=20,right=20,),horizontal_alignment=HorizontalAlignment.CENTER,vertical_alignment=VerticalAlignment.CENTER,),...Having executed the script, we will get the following image:Success!But what do we do if we need to change the text in the image often?For this purpose, the template provides a context:...fromimage_patternimport(...Context,)...classAvatarContext(Context):first_char:strsecond_char:str...Text(text=AvatarContext.var('first_char'),...),Text(text=AvatarContext.var('second_char'),...),...context=AvatarContext(first_char='I',second_char='P',)avatar_pattern=Avatar(context=context)...Now we can change the content of the generated image without changing the template itself.See the full code of the example in./examples/avatar.py.APIAll classes are inherited frompydantic.BaseModelto validate passed
arguments, which imposes certain specifics when working with api.PatternBasic template class.The template must be inherited from it.To create a template, you need to override the following attributes:canvas - attribute of theCanvastype. Sets the properties of the
canvas.layers - attribute of theList[Layer]type. Sets a list of
layers.The object constructor accepts the following arguments:context - an argument of theContexttype that will be passed to
the elements to form their properties.Methods of the object:render - returns the generated image object of thePIL.Imagetype;render_to_blob(**save_kwargs) - returns the generated image object of theio.BytesIOtype. Accepts the parameters passed to the methodPIL.Image.save(),such asqualityand etc. You cannot pass the image format, as it is saved inJPEG. Made simply for easy use of the generation results.CanvasThe object describing the properties of the canvas.The object constructor accepts the following arguments:size - is the size of the canvas. It can be set asTuple[int, int]as well as context variable.LayerAn object that describes a layer containing image content.The layers are overlapping, starting from the first layer in the list - the bottom layer, and ending with the last layer in the list - the top layer.The object constructor accepts the following arguments:*elements - a list of itemsRecatngleorTextto add to the image.ContextAn object that describes the context of an image. The context is described by the object attributes.The context is an heir topydantic.BaseModel, so it requires a description of the types to perform the validation.Methods of the object:var(attribute_name: str) - indicates which context variable to use for this attribute.Positionable elementsRectangleAn object that adds rectangles to an image.The object constructor accepts the following arguments:point -Pointobject, which points to the upper left corner of
the element in the image;horizontal_alignment - one of the values of the enumerationHorizontalAlignment, to specify the horizontal alignment. Can be
set from a context variable. By default -HorizontalAlignment.LEFT;vertical_alignment - one of the values of the enumerationVerticalAlignment, to specify the vertical alignment. Can be set
from a context variable. By default -VerticalAlignment.TOP;size - element size. It can be set asTuple[int, int]as well as
context variable;brightness - element brightness. Optional argument. It ca be set asfloatfrom 0 to 1 or context variable;background_image - sets the background image for the element.
Optional argument. Must set the path to the image. Can be set from a
context variable. The background image is scaled to the same extent
as set in css -background-size:cover;.background_color - sets the color of background of the element.
Optional argument if setbackground_image. Used when generating
an element only when the propertybackground_imageis not set.
It can be set as RGBTuple[int, int, int]or RGBATuple[int, int, int]. Can be set from a context variable.alpha - alpha assignment. Optional argument. It can be set asintfrom 0 to 255. Can be set from a context variable.TextAn object that adds text to the image.The object constructor accepts the following arguments:point -Pointobject, which points to the upper left corner of
the element in the image;horizontal_alignment - one of the values of the enumerationHorizontalAlignment, to specify the horizontal alignment. Can be
set from a context variable. By default -HorizontalAlignment.LEFT;vertical_alignment - one of the values of the enumerationVerticalAlignment, to specify the vertical alignment. Can be set
from a context variable. By default -VerticalAlignment.TOP;font - specifies the font to be used for text. Presented as a path to
OpenType or TrueType font. Can be set from a context variable.font_size - sets the font size. It can be represented by aintor context variable. By default -12;font_color - sets the font color as RGBTuple[int, int, int].
Can be set from context variable. By default -(0, 0, 0);text - specifies, directly, the text to be added to the image. It can
be set asstror context variable;line_height - sets the height of the line. Optional argument. It can
be set asintor context variable;margin - sets the indents for the text relative to the canvas.
Optional argument. It can be set asPositionor context variable;Support objectsPointDescribes the point on the canvas.The object constructor accepts the following arguments:x - x coordinate asint;y - y coordinate asint.PositionDescribes the position of the element relative to the sides of the
canvas. For example, indents for text.top -intindented from the top edge of the canvas;right -intindented from the right edge of the canvas;bottom -intindented from the bottom edge of the canvas;left -intindented from the left edge of the canvas.EnumsHorizontalAlignmentProvides horizontal alignment options.ValuesHorizontalAlignment.LEFT - left edge alignment;HorizontalAlignment.CENTER - center alignment;HorizontalAlignment.RIGHT - right edge alignment.VerticalAlignmentProvides vertical alignment options.ValuesVerticalAlignment.TOP - top edge alignment;VerticalAlignment.CENTER - center alignment;VerticalAlignment.BOTTOM - bottom edge alignment.IntegrationsDjangoFor integration with django, the package provides theimage_pattern.cotrib.ImagePatternFieldfield inherited fromdjango.db.models.ImageField.The field has a preset elementblank = Truerelative toImageFieldand a number of new arguments:pattern - image pattern;context -callbackobject method that returns the context for
generating the image. Optional argument.
if the method is not specified, the object methodget_image_pattern_contextwill be used;should_be_created -callbackobject method, indicating the need
to generate an image. Optional argument. The method is not specified, the object methodimage_pattern_should_be_createdwill be used.The image is generated if the field is empty andshould_be_createdreturnsTrue.For more informationImagePatternFieldsee the example project in./django_example.TODO[ ] Make it possible to change the image format.[ ] Do something with the autocomplete to create objects (Since all
objects are inherited from pydantic.BaseModel, they do not contain
meta information for the autocomplete. Perhaps should manually write
all the constructors.).[ ] Think about using context. Using Context.var() with a string name
does not seem to be the best way.[ ] Make it possible to shift within the layer not only to down, but
also to the right.[ ] Setting the center of the background image.[ ] Test refactoring and bringing coverage to 100%.[ ] Setup linter.[ ] Check with mypy.[ ] Setup github actions.