Usage

This article is a tutorial for nider package and at the same time it is a full reference of all nider models and possibilities.

Image units

There are three main units each nider.Image can consist of:

  • header
  • paragraph
  • linkback
_images/available_units.png

Each of the units is represented by a class in nider.models:

nider.models.Header

class nider.models.Header(text, font=None, text_width=21, line_padding=6, color=None, outline=None, align='center')[source]

Class that represents a header used in images

Parameters:
  • text (str) – text used for the unit.
  • font (nider.core.Font) – font object that represents text’s font.
  • text_width (int) – units’s text width - number of characters in a line.
  • line_padding (int) – unit’s line padding - padding (in pixels) between the lines.
  • color (str) – string that represents a color. Must be compatible with PIL.ImageColor color names.
  • outline (nider.core.Outline) – outline object that represents text’s outline.
  • align ('left' or 'center' or 'right') – side with respect to which the text will be aligned.
Raises:

Example

from nider.core import Font
from nider.core import Outline
from nider.models import Header

header = Header(text='Your super interesting title!',
                font=Font('/home/me/.local/share/fonts/Roboto/Roboto-Bold.ttf', 30),
                text_width=40,
                align='left',
                color='#ededed',
                outline=Oultine(2, '#222')
                )

nider.models.Paragraph

This class has the same attribures and behaviour as nider.models.Header.

class nider.models.Paragraph(text, font=None, text_width=21, line_padding=6, color=None, outline=None, align='center')[source]

Class that represents a paragraph used in images

Parameters:
  • text (str) – text used for the unit.
  • font (nider.core.Font) – font object that represents text’s font.
  • text_width (int) – units’s text width - number of characters in a line.
  • line_padding (int) – unit’s line padding - padding (in pixels) between the lines.
  • color (str) –

    string that represents a color. Must be compatible with PIL.ImageColor color names.

  • outline (nider.core.Outline) – outline object that represents text’s outline.
  • align ('left' or 'center' or 'right') – side with respect to which the text will be aligned.
Raises:

Example

from nider.core import Font
from nider.core import Outline
from nider.models import Paragraph

para = Paragraph(text='Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.',
                 font=Font('/home/me/.local/share/fonts/Roboto/Roboto-Bold.ttf', 30),
                 text_width=65,
                 align='left',
                 color='#ededed'
                 outline=Oultine(1, '#000')
                 )

nider.models.Linkback

class nider.models.Linkback(text, font=None, color=None, outline=None, align='right', bottom_padding=20)[source]

Class that represents a linkback used in images

Parameters:
  • text (str) – text used for the unit.
  • font (nider.core.Font) – font object that represents text’s font.
  • color (str) –

    string that represents a color. Must be compatible with PIL.ImageColor color names

  • outline (nider.core.Outline) – outline object that represents text’s outline.
  • align ('left' or 'center' or 'right') – side with respect to which the text will be aligned.
  • bottom_padding (int) – linkback’s bottom padding - padding (in pixels) between the bottom of the image and the linkback itself.
Raises:

Example

from nider.core import Font
from nider.core import Outline
from nider.models import Linkback

linkback = Linkback(text='foo.com | @username',
                    font=Font('/home/me/.local/share/fonts/Roboto/Roboto-Bold.ttf', 30),
                    color='#ededed',
                    outline=Oultine(2, '#000')
                    )

Note

Parameters color and outline.color are optional for any unit. They can be generated automatically by nider. nider analyzes background color of either a texture or of an image and chooses an opposite one to it. So if your image in mainly dark , white text color will be auto generated and set. The same applies to outline color.

Although it’s a nice feature for backgrounds you have no control over, we’d recommend to provide colors explicitly.

Image content

In order to aggregate all of the units together you need to create an instance of nider.models.Content class.

nider.models.Content

class nider.models.Content(paragraph=None, header=None, linkback=None, padding=45)[source]

Class that aggregates different units into a sigle object

Parameters:
Raises:

nider.exceptions.ImageGeneratorException – if neither of paragraph, header or linkback is provided.

Note

padding is taken into account only if image is to get resized. If size allows content to fit freely, pre-calculated paddings will be used.

Note

Content has to consist at least of one unit: header, paragraph or linkback.

Example

from nider.models import Content
from nider.models import Linkback
from nider.models import Paragraph

para = Paragraph(...)

linkback = Linkback(...)

content = Content(para, linkback=linkback, padding=60)

Initializing an image

After the content is prepared it’s the right time to initialize an image. In nider a basic image is represented by nider.models.Image.

nider.models.Image

class nider.models.Image(content, fullpath, width=1080, height=1080, title=None, description=None)[source]

Base class for a text based image

Parameters:
  • content (nider.models.Content) – content object that has units to be rendered.
  • fullpath (str) – path where the image has to be saved.
  • width (int) – width of the image to be generated.
  • height (int) – height of the image to be generated.
  • title (str) – title of the image. Serves as metadata for latter rendering in html. May be used as alt text of the image. If no title is provided content.header.text will be set as the value.
  • description (str) – description of the image. Serves as metadata for latter rendering in html. May be used as description text of the image. If no description is provided content.paragraph.text will be set as the value.
Raises:

Example

from nider.models import Content
from nider.models import Image

content = Content(...)

img = Image(content,
            fullpath='example.png',
            width=500,
            height=500
            )

Social media images

nider comes with some pre-built models that can be used to generate images for some social networks. These are subclasses of nider.models.Image with changed size.

Facebook
Twitter

I highly recommend reading this post if you are curious about what are the right image sizes for social media images.

Drawing on the image

Having an instance of nider.models.Image we are ready to create a real image.

nider comes with 3 options of drawing your image:

  • Image.draw_on_texture - draws preinitialized image and its attributes on a texture.

Note

You don’t need to create textured images by pasting texture mulpitle times in Photoshop or Gimp. nider takes care of filling image of any size with textrure you privide.

  • Image.draw_on_bg - Draws preinitialized image and its attributes on a colored background. nider uses a color you provide to fill the image and then draws the content.
  • Image.draw_on_image - Draws preinitialized image and its attributes on an image. Content will be drawn directly on the image you provide.

Image.draw_on_texture

Image.draw_on_texture(texture_path=None)[source]

Draws preinitialized image and its attributes on a texture

If texture_path is set to None, random texture from nider/textures will be taken.

Parameters:

texture_path (str) – path of the texture to use.

Raises:
  • FileNotFoundError – if texture file at path texture_path cannot be found.
  • nider.exceptions.ImageSizeFixedWarning – if the image size has to be adjusted to the provided content’s size because the content takes too much space.

Example

from nider.models import Content
from nider.models import Image

content = Content(...)

img = Image(content,
            fullpath='example.png',
            width=500,
            height=500
            )

img.draw_on_texture('example_texture.png')

Check the full example here .


nider comes with a huge bundle of textures. As for now you need to copy them to your machine if you want to use any of them.

Image.draw_on_bg

Image.draw_on_bg(bgcolor=None)[source]

Draws preinitialized image and its attributes on a colored background

If bgcolor is set to None, random nider.colors.colormap.FLAT_UI_COLORS will be taken.

Parameters:bgcolor (str) –

string that represents a background color. Must be compatible with PIL.ImageColor color names

Raises:nider.exceptions.ImageSizeFixedWarning – if the image size has to be adjusted to the provided content’s size because the content takes too much space.

Example

from nider.models import Content
from nider.models import Image

content = Content(...)

img = Image(content,
            fullpath='example.png',
            width=500,
            height=500
            )

img.draw_on_bg('#efefef')

Check the full example here .

Image.draw_on_image

Image.draw_on_image(image_path, image_enhancements=None, image_filters=None)[source]

Draws preinitialized image and its attributes on an image

Parameters:
  • image_path (str) – path of the image to draw on.
  • image_enhancements (itarable) – itarable of tuples, each containing a class from PIL.ImageEnhance that will be applied and factor - a floating point value controlling the enhancement. Check documentation of PIL.ImageEnhance for more info about availabe enhancements.
  • image_filters (itarable) –

    itarable of filters from PIL.ImageFilter that will be applied. Check documentation of PIL.ImageFilter for more info about availabe filters.

Raises:

FileNotFoundError – if image file at path image_path cannot be found.

Examples

from nider.models import Content
from nider.models import Image

content = Content(...)

img = Image(content,
            fullpath='example.png',
            width=500,
            height=500
            )

img.draw_on_image('example_bg.jpg')

Using filters and enhancements:

img.draw_on_image('example_bg.jpg',
                  image_enhancements=((ImageEnhance.Contrast, 0.75),
                                     (ImageEnhance.Brightness, 0.5)),
                  image_filters=((ImageFilter.BLUR),),
                  )

Check the full example here .


That’s it. After any of draw methods has been called and successfully completed the new image will be saved to Image.fullpath.