Documentation – Visual Parameters & Layout

Java: Customize Barcode Backgrounds

Mon, 01 Jan 0001 00:00:00 +0000

Customize Barcode Backgrounds

Aspose.BarCode for Java allows you to configure the background of a generated barcode image, including solid colors, transparent backgrounds, and semi-transparent backgrounds.

Background settings do not change the encoded data, but they can affect recognition reliability.

The complete source code for the examples in this article is available on GitHub:

View BackgroundsExample.java

set

Set a solid background color

Use setBackColor to configure the image background.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.QR,
        "BACKGROUND-EXAMPLE"
);

generator.getParameters().setBackColor(
        new Color(245, 248, 252)
);

generator.getParameters()
        .getBarcode()
        .setBarColor(new Color(20, 45, 90));

generator.save(
        "qr_custom_background.png",
        BarCodeImageFormat.PNG
);

A light background with dark modules usually provides reliable recognition.

Use a dark background

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.QR,
        "DARK-BACKGROUND"
);

generator.getParameters().setBackColor(Color.BLACK);

generator.getParameters()
        .getBarcode()
        .setBarColor(Color.WHITE);

generator.save(
        "qr_dark_background.png",
        BarCodeImageFormat.PNG
);

Inverted barcodes can be less compatible with some readers. Use dark bars or modules on a light background when maximum interoperability is required.

Create a transparent background

PNG supports an alpha channel. A fully transparent background can be created with an alpha value of 0.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.QR,
        "TRANSPARENT-QR"
);

generator.getParameters().setBackColor(
        new Color(255, 255, 255, 0)
);

generator.save(
        "qr_transparent.png",
        BarCodeImageFormat.PNG
);

The barcode modules remain visible, while the configured background area is transparent.

Create a semi-transparent background

Use an alpha value between 0 and 255 to create a semi-transparent background.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.QR,
        "SEMI-TRANSPARENT-QR"
);

generator.getParameters().setBackColor(
        new Color(255, 255, 255, 128)
);

generator.save(
        "qr_semi_transparent.png",
        BarCodeImageFormat.PNG
);

The alpha value ranges from:

0 — fully transparent;
255 — fully opaque.

Not all image formats preserve transparency. JPEG does not support an alpha channel.

Configure padding around the barcode

Padding adds blank space around the generated barcode image.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "PADDING-EXAMPLE"
);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getLeft()
        .setPixels(20);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getRight()
        .setPixels(20);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getTop()
        .setPixels(10);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getBottom()
        .setPixels(10);

generator.save(
        "code128_with_padding.png",
        BarCodeImageFormat.PNG
);

Padding is an image-layout setting. Left and right padding can reserve space for required quiet zones, but the required quiet-zone width depends on the symbology, X-dimension, and applicable barcode specification.

Validate transparency in tests

The related Java example checks generated PNG images with ImageIO and confirms that transparent or semi-transparent alpha values are actually present in the output.

This verifies that the selected image format preserved the requested transparency instead of checking only that a file was created.

Recommendations

Maintain strong contrast between the barcode and its final background.
Test transparent images after placing them on the actual destination background.
Use an output format that preserves the required alpha channel.
Keep enough blank space around the symbol.
Do not treat arbitrary padding values as universal quiet-zone dimensions.
Validate the final image with the intended scanner and rendering pipeline.

Java: Customize Barcode Size

Mon, 01 Jan 0001 00:00:00 +0000

Customize Barcode Size

Barcode size is determined by the encoded data, X-dimension, vertical dimensions, padding, captions, and optional fixed image bounds.

Set X-dimension and bar height

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "SIZE-1D"
);

generator.getParameters().setAutoSizeMode(AutoSizeMode.NONE);
generator.getParameters().getBarcode().getXDimension().setPixels(3.0f);
generator.getParameters().getBarcode().getBarHeight().setPixels(100);

X-dimension is the width of the smallest module or narrow bar. See the X-dimension overview.

Use auto-size modes

AutoSizeMode.NONE preserves explicitly configured dimensions. AutoSizeMode.NEAREST calculates a suitable barcode size for the image box. AutoSizeMode.INTERPOLATION scales the generated image to the requested bounds and may introduce resampling.

generator.getParameters().setAutoSizeMode(AutoSizeMode.NEAREST);
generator.getParameters().getImageWidth().setPixels(240);
generator.getParameters().getImageHeight().setPixels(240);

When NEAREST is enabled, explicit X-dimension and bar-height values are not the controlling dimensions.

Symbology-specific dimensions

Some barcode types expose additional size parameters:

AustralianPostShortBarHeight controls short bars in Australian Post symbols;
ITF-14 bearer-bar thickness and border type control the surrounding frame;
QR version determines the module matrix size;
Data Matrix version selects a fixed matrix configuration;
PDF417 columns, rows, and aspect ratio influence the rectangular layout.

See the QR Code standard overview, Data Matrix standard overview, and PDF417 standard overview for structural details.

Always verify the final dimensions against the applicable barcode specification, printer process, label material, and scanner environment.

Complete example

View CustomizingSizeExample.java

set

Java: Customize Barcode Borders

Mon, 01 Jan 0001 00:00:00 +0000

Customize Barcode Borders

Aspose.BarCode for Java can draw a border around the generated barcode image. You can configure border visibility, color, width, and line style.

For ITF-14, separate bearer-bar settings are available because bearer bars are part of the symbology-specific layout rather than a decorative image border.

The complete source code for the examples in this article is available on GitHub:

View BordersExample.java

set

Enable an image border

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "BORDER-EXAMPLE"
);

generator.getParameters()
        .getBorder()
        .setVisible(true);

generator.save(
        "code128_border.png",
        BarCodeImageFormat.PNG
);

Set border color and width

generator.getParameters()
        .getBorder()
        .setColor(Color.GRAY);

generator.getParameters()
        .getBorder()
        .getWidth()
        .setPixels(2);

Set the border line style

generator.getParameters()
        .getBorder()
        .setDashStyle(BorderDashStyle.SOLID);

Depending on the library version, additional dash styles can be available.

A decorative border should remain visually separate from the barcode bars or modules. Provide enough padding so that the border does not intrude into the required blank margins.

Use a border with a custom background

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "BORDER-STYLE"
);

generator.getParameters().setBackColor(
        new Color(245, 248, 252)
);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getLeft()
        .setPixels(20);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getRight()
        .setPixels(20);

generator.getParameters()
        .getBorder()
        .setVisible(true);

generator.getParameters()
        .getBorder()
        .setColor(Color.DARK_GRAY);

generator.getParameters()
        .getBorder()
        .getWidth()
        .setPixels(2);

generator.save(
        "code128_border_complete.png",
        BarCodeImageFormat.PNG
);

Configure ITF-14 bearer bars

ITF-14 uses bearer bars that are specific to the symbology.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.ITF_14,
        "12345678901231"
);

generator.getParameters()
        .getBarcode()
        .getITF()
        .setItfBorderType(ITF14BorderType.FRAME);

generator.getParameters()
        .getBarcode()
        .getITF()
        .getItfBorderThickness()
        .setPixels(4);

generator.save(
        "itf14_frame.png",
        BarCodeImageFormat.PNG
);

Available bearer-bar layouts can include frame and bar variants. The exact physical dimensions should be validated against the applicable barcode specification and printing process.

Recommendations

Keep decorative borders outside the required quiet zones.
Use sufficient padding between the barcode and the border.
Avoid thick borders near linear barcode bars.
Treat ITF-14 bearer bars as symbology-specific elements.
Validate the result with the intended printer and scanner.

Java: Customize Barcode Colors

Mon, 01 Jan 0001 00:00:00 +0000

Customize Barcode Colors

Aspose.BarCode for Java allows you to customize the colors of barcode bars, two-dimensional modules, captions, and human-readable code text.

The complete source code for the examples in this article is available on GitHub:

View ColorsExample.java

set

Set the bar or module color

Use setBarColor to configure the foreground color of a barcode.

For linear symbologies, this setting changes the bar color. For two-dimensional symbologies, it changes the module color.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "COLOR-EXAMPLE"
);

generator.getParameters()
        .getBarcode()
        .setBarColor(Color.DARK_GRAY);

generator.save(
        "code128_dark_gray.png",
        BarCodeImageFormat.PNG
);

Use a custom RGB color

Color darkBlue = new Color(20, 45, 90);

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.QR,
        "CUSTOM-RGB"
);

generator.getParameters()
        .getBarcode()
        .setBarColor(darkBlue);

generator.save(
        "qr_dark_blue.png",
        BarCodeImageFormat.PNG
);

Set human-readable text color

Human-readable code text is configured through CodetextParameters.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "TEXT-COLOR"
);

generator.getParameters()
        .getBarcode()
        .getCodeTextParameters()
        .setColor(Color.BLUE);

generator.save(
        "code128_text_color.png",
        BarCodeImageFormat.PNG
);

Set caption colors

Caption colors are configured independently for the upper and lower captions.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "CAPTION-COLOR"
);

generator.getParameters()
        .getCaptionAbove()
        .setVisible(true);

generator.getParameters()
        .getCaptionAbove()
        .setText("Inventory");

generator.getParameters()
        .getCaptionAbove()
        .setTextColor(Color.RED);

generator.getParameters()
        .getCaptionBelow()
        .setVisible(true);

generator.getParameters()
        .getCaptionBelow()
        .setText("Warehouse A");

generator.getParameters()
        .getCaptionBelow()
        .setTextColor(Color.BLUE);

generator.save(
        "code128_caption_colors.png",
        BarCodeImageFormat.PNG
);

Use light modules on a dark background

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.QR,
        "LIGHT-ON-DARK"
);

generator.getParameters().setBackColor(Color.BLACK);

generator.getParameters()
        .getBarcode()
        .setBarColor(Color.WHITE);

generator.save(
        "qr_light_on_dark.png",
        BarCodeImageFormat.PNG
);

Not all scanners process inverted barcodes equally well. Dark bars or modules on a light background remain the safest choice for broad interoperability.

Recommendations

Maintain strong contrast between the barcode and the background.
Avoid combinations with similar luminance.
Test custom colors with the target scanner and printer.
Verify caption and code-text readability separately.
Prefer dark foreground colors on a light background for critical applications.

Java: Customize Barcode Captions

Mon, 01 Jan 0001 00:00:00 +0000

Customize Barcode Captions

Aspose.BarCode for Java supports two independent caption areas:

CaptionAbove renders text above the barcode;
CaptionBelow renders text below the barcode.

Captions are independent from the encoded payload. They can contain titles, product names, instructions, warehouse locations, batch information, or any other descriptive text.

The complete source code for the examples in this article is available on GitHub:

View CustomizingCaptionsExample.java

Captions and human-readable code text

Captions and human-readable code text serve different purposes.

Human-readable code text represents the encoded barcode value and is configured through CodetextParameters.

Captions are independent labels configured through CaptionParameters.

To use a caption as the only visible text, hide the built-in human-readable code text:

generator.getParameters()
        .getBarcode()
        .getCodeTextParameters()
        .setLocation(CodeLocation.NONE);

Hiding the human-readable text does not change the encoded barcode payload.

Add a caption above a barcode

The following example adds a centered title above a QR Code.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.QR,
        "QR-TITLE"
);

generator.getParameters()
        .getBarcode()
        .getCodeTextParameters()
        .setLocation(CodeLocation.NONE);

CaptionParameters captionAbove =
        generator.getParameters().getCaptionAbove();

captionAbove.setVisible(true);
captionAbove.setText("SCAN ME");
captionAbove.getFont().getSize().setPoint(14);
captionAbove.setAlignment(TextAlignment.CENTER);
captionAbove.getPadding().getBottom().setPoint(8);

generator.save(
        "qr_title_only.png",
        BarCodeImageFormat.PNG
);

CaptionAbove.getPadding().getBottom() controls the space between the upper caption and the barcode.

Add captions above and below

Upper and lower captions can be displayed at the same time.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "ABOVE-BELOW"
);

generator.getParameters()
        .getBarcode()
        .getCodeTextParameters()
        .setLocation(CodeLocation.NONE);

CaptionParameters captionAbove =
        generator.getParameters().getCaptionAbove();

captionAbove.setVisible(true);
captionAbove.setText("INVENTORY LABEL");
captionAbove.getFont().getSize().setPoint(12);
captionAbove.setAlignment(TextAlignment.CENTER);
captionAbove.getPadding().getBottom().setPoint(6);

CaptionParameters captionBelow =
        generator.getParameters().getCaptionBelow();

captionBelow.setVisible(true);
captionBelow.setText("SKU-001-RED");
captionBelow.getFont().getSize().setPoint(10);
captionBelow.setAlignment(TextAlignment.CENTER);
captionBelow.getPadding().getTop().setPoint(8);

generator.save(
        "code128_above_and_below.png",
        BarCodeImageFormat.PNG
);

The upper and lower captions have separate text, font, color, alignment, and padding settings.

Configure caption alignment

Use TextAlignment to align caption text horizontally.

CaptionParameters caption =
        generator.getParameters().getCaptionBelow();

caption.setVisible(true);
caption.setText("WAREHOUSE A");
caption.setAlignment(TextAlignment.CENTER);

Available alignment values include:

TextAlignment.LEFT
TextAlignment.CENTER
TextAlignment.RIGHT

The visual effect is easiest to see when the output image is wider than the caption text.

Configure caption font size

Caption font size is configured through the caption font unit.

CaptionParameters caption =
        generator.getParameters().getCaptionBelow();

caption.setVisible(true);
caption.setText("CAPTION 14pt");
caption.getFont().getSize().setPoint(14);

Point units are convenient when the output is intended for print because they represent typographic size rather than a fixed number of pixels.

The requested font must be available in the runtime environment. Otherwise, Java can substitute another installed font.

Configure caption color

Use setTextColor to set the caption text color.

CaptionParameters caption =
        generator.getParameters().getCaptionBelow();

caption.setVisible(true);
caption.setText("BRAND CAPTION");
caption.setTextColor(new Color(0, 128, 128));

The caption color can be matched to the barcode bar color for a consistent visual style.

Color brandColor = new Color(30, 30, 30);

generator.getParameters()
        .getBarcode()
        .setBarColor(brandColor);

generator.getParameters()
        .getCaptionBelow()
        .setTextColor(brandColor);

Maintain sufficient contrast between caption text and the image background.

Configure caption padding

Each caption has independent padding on all sides.

CaptionParameters caption =
        generator.getParameters().getCaptionBelow();

caption.getPadding().getTop().setPoint(6);
caption.getPadding().getLeft().setMillimeters(2.0f);
caption.getPadding().getRight().setPixels(10);

Padding can be specified in different units:

pixels for exact raster spacing;
points for typographic layouts;
millimeters or inches for print-oriented layouts.

For a caption above the barcode, bottom padding controls the gap toward the symbol.

For a caption below the barcode, top padding controls the gap toward the symbol.

Use DPI-aware caption spacing

A Unit value can be associated with a specific resolution before converting physical or typographic units to pixels.

CaptionParameters captionAbove =
        generator.getParameters().getCaptionAbove();

Unit bottomPadding =
        captionAbove.getPadding().getBottom();

bottomPadding.updateResolution(203.0f);
bottomPadding.setPoint(10.0f);

This is useful for thermal-printer layouts where the same physical spacing must be converted for a known printer resolution.

Create multiline captions

Captions can contain explicit line breaks.

CaptionParameters caption =
        generator.getParameters().getCaptionBelow();

caption.setVisible(true);
caption.setText("PICK FACE\nAISLE 12");
caption.setNoWrap(false);
caption.getFont().getSize().setPoint(11);
caption.setAlignment(TextAlignment.CENTER);

setNoWrap(false) allows the caption text to wrap when the available image width is limited.

Provide enough image height for all caption lines and the barcode symbol.

Combine a title with human-readable code text

A caption can be used as a title while the barcode value remains visible below the symbol.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.EAN_13,
        "5901234123457"
);

generator.getParameters()
        .getBarcode()
        .getCodeTextParameters()
        .setLocation(CodeLocation.BELOW);

CaptionParameters captionAbove =
        generator.getParameters().getCaptionAbove();

captionAbove.setVisible(true);
captionAbove.setText("PRODUCT LABEL");
captionAbove.getFont().getSize().setPoint(12);
captionAbove.setAlignment(TextAlignment.CENTER);
captionAbove.getPadding().getBottom().setPoint(6);

The caption text does not replace or modify the EAN-13 payload.

Configure compact caption layouts

For compact labels, use a small font and exact pixel spacing.

CaptionParameters caption =
        generator.getParameters().getCaptionBelow();

caption.setVisible(true);
caption.setText("LOT 24");
caption.getFont().getSize().setPoint(8);
caption.getPadding().getTop().setPixels(4);
caption.setAlignment(TextAlignment.CENTER);

Test compact layouts at the final print resolution. A caption that looks readable on screen may become too small after printing.

Recommendations

Use captions for descriptive text that is not part of the encoded payload.
Hide human-readable code text only when the layout requires it.
Keep caption text visually separate from barcode bars and modules.
Provide enough image width and height for the selected font and padding.
Use point, millimeter, or inch units for print-oriented layouts.
Verify that the required fonts are installed in the runtime environment.
Test multiline and compact captions with the final renderer and printer.

Java: Customize Text and Font

Mon, 01 Jan 0001 00:00:00 +0000

Customize Human-Readable Text and Font

Human-readable text displays the encoded barcode value as text near the barcode symbol.

In Aspose.BarCode for Java, it is configured through CodetextParameters:

CodetextParameters codeTextParameters =
        generator.getParameters()
                .getBarcode()
                .getCodeTextParameters();

Changes to human-readable text affect only the visual representation. They do not change the encoded payload.

The complete source code for the examples in this article is available on GitHub:

View TextAndFontExample.java

Place human-readable text below the barcode

Use CodeLocation.BELOW to display the encoded value below the bars.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "HRI-BELOW"
);

generator.getParameters()
        .getBarcode()
        .getCodeTextParameters()
        .setLocation(CodeLocation.BELOW);

generator.save(
        "c128_hri_below_default.png",
        BarCodeImageFormat.PNG
);

This is a common layout for linear barcodes.

Place human-readable text above the barcode

Use CodeLocation.ABOVE to display the text above the barcode.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "ABOVE-14PT-BLUE"
);

CodetextParameters codeText =
        generator.getParameters()
                .getBarcode()
                .getCodeTextParameters();

codeText.setLocation(CodeLocation.ABOVE);
codeText.getFont().getSize().setPoint(14);
codeText.setColor(Color.BLUE);

generator.save(
        "c128_hri_above_14pt_blue.png",
        BarCodeImageFormat.PNG
);

The barcode payload remains unchanged and can still be decoded as ABOVE-14PT-BLUE.

Hide human-readable text

Use CodeLocation.NONE when the barcode value should not be rendered as text.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.UPCA,
        "042100005264"
);

generator.getParameters()
        .getBarcode()
        .getCodeTextParameters()
        .setLocation(CodeLocation.NONE);

generator.save(
        "upca_hri_none.png",
        BarCodeImageFormat.PNG
);

This setting hides only the visible text. It does not remove the encoded data.

This layout is useful when:

text is rendered separately by the application;
independent captions are used;
the barcode must fit into a compact image area.

Configure font size

The font size is configured through the code-text font unit.

CodetextParameters codeText =
        generator.getParameters()
                .getBarcode()
                .getCodeTextParameters();

codeText.getFont().getSize().setPoint(12);

The example project compares 8-point and 16-point human-readable text using the same Code 128 payload.

BarcodeGenerator generatorSmall = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "FONT-COMPARE"
);

generatorSmall.getParameters()
        .getBarcode()
        .getCodeTextParameters()
        .getFont()
        .getSize()
        .setPoint(8);

BarcodeGenerator generatorLarge = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "FONT-COMPARE"
);

generatorLarge.getParameters()
        .getBarcode()
        .getCodeTextParameters()
        .getFont()
        .getSize()
        .setPoint(16);

Choose the font size according to the final image dimensions and print resolution.

Configure text color

Use setColor to change the color of the human-readable text.

CodetextParameters codeText =
        generator.getParameters()
                .getBarcode()
                .getCodeTextParameters();

codeText.setColor(Color.BLUE);

The text color is independent from the barcode bar or module color.

Maintain enough contrast between the text and the background.

Configure text alignment

Use TextAlignment to control horizontal placement.

CodetextParameters codeText =
        generator.getParameters()
                .getBarcode()
                .getCodeTextParameters();

codeText.setLocation(CodeLocation.BELOW);
codeText.setAlignment(TextAlignment.RIGHT);

Available values include:

TextAlignment.LEFT
TextAlignment.CENTER
TextAlignment.RIGHT

Alignment is most visible when the generated image is wider than the rendered text.

Configure spacing between the barcode and text

Use CodetextParameters.getSpace() to control the gap between the symbol and the human-readable text.

CodetextParameters codeText =
        generator.getParameters()
                .getBarcode()
                .getCodeTextParameters();

codeText.setLocation(CodeLocation.BELOW);

Unit textGap = codeText.getSpace();
textGap.setPoint(10.0f);

Spacing can be configured in different units, including pixels, points, millimeters, and inches.

Point-based spacing is converted to pixels according to the unit resolution.

Configure human-readable text for EAN-13

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.EAN_13,
        "5901234123457"
);

CodetextParameters codeText =
        generator.getParameters()
                .getBarcode()
                .getCodeTextParameters();

codeText.setLocation(CodeLocation.BELOW);
codeText.getSpace().setPoint(10.0f);

generator.save(
        "ean13_hri_below_space_pt.png",
        BarCodeImageFormat.PNG
);

EAN and UPC symbologies have standardized text layouts. Always verify that visual customization remains suitable for the target application and scanning environment.

Configure human-readable text for QR Code

Two-dimensional barcodes can also display human-readable text.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.QR,
        "QR-UTF8"
);

generator.getParameters()
        .getBarcode()
        .getQR()
        .setECIEncoding(ECIEncodings.UTF8);

CodetextParameters codeText =
        generator.getParameters()
                .getBarcode()
                .getCodeTextParameters();

codeText.setLocation(CodeLocation.ABOVE);
codeText.getFont().getSize().setPoint(12);

generator.save(
        "qr_hri_above_utf8_12pt.png",
        BarCodeImageFormat.PNG
);

The ECI setting controls the QR payload encoding. The human-readable text settings control only how the payload is displayed near the symbol.

Configure image size for text layouts

Human-readable text requires additional vertical space.

generator.getParameters()
        .getImageWidth()
        .setPixels(360);

generator.getParameters()
        .getImageHeight()
        .setPixels(180);

If the output image is too small, text can become compressed, clipped, or difficult to read.

When increasing the font size or spacing, increase the image height as needed.

Human-readable text and captions

Human-readable text always represents the encoded payload.

Captions are independent labels and can contain arbitrary text.

Use human-readable text when the visible value must match the barcode payload. Use captions for titles, instructions, product descriptions, or other supporting information.

Recommendations

Keep the visible text consistent with the encoded payload.
Use CodeLocation.NONE only when hiding the text is intentional.
Select a font size suitable for the final output dimensions.
Provide enough vertical space for the font and text gap.
Maintain strong text-to-background contrast.
Verify alignment and spacing in the generated image.
Test EAN and UPC layouts with the intended application requirements.
Confirm that the output remains readable after printing or image scaling.

Java: Rotate Barcode Images

Mon, 01 Jan 0001 00:00:00 +0000

Rotate Barcode Images

Aspose.BarCode for Java allows you to rotate the complete generated barcode image without changing the encoded data.

Rotation is applied to:

barcode bars or modules;
human-readable code text;
captions;
padding;
borders.

The complete source code for the examples in this article is available on GitHub:

View RotationExample.java

set

Rotate a barcode by 90 degrees

Use setRotationAngle to rotate a generated image clockwise.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "ROTATE-90"
);

generator.getParameters().setRotationAngle(90.0f);

generator.save(
        "code128_rotate_90.png",
        BarCodeImageFormat.PNG
);

Right-angle rotations such as 90, 180, and 270 degrees usually preserve crisp barcode geometry and are broadly compatible with scanners.

Rotate a barcode by 180 degrees

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "ROTATE-180"
);

generator.getParameters().setRotationAngle(180.0f);

generator.save(
        "code128_rotate_180.png",
        BarCodeImageFormat.PNG
);

Use a negative rotation angle

Negative values rotate the image counterclockwise.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "ROTATE-NEGATIVE"
);

generator.getParameters().setRotationAngle(-90.0f);

generator.save(
        "code128_rotate_negative_90.png",
        BarCodeImageFormat.PNG
);

Rotate by an arbitrary angle

The API accepts arbitrary angle values.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.QR,
        "ARBITRARY-ANGLE"
);

generator.getParameters().setRotationAngle(25.0f);

generator.save(
        "qr_rotate_25.png",
        BarCodeImageFormat.PNG
);

Angles that are not multiples of 90 degrees can require a larger output canvas and may introduce interpolation around barcode edges. This can reduce recognition reliability for small or low-resolution images.

Recommendations

Prefer 90, 180, and 270 degree rotations when possible.
Use a sufficiently large module or bar width.
Keep enough padding so that the rotated symbol is not clipped.
Test arbitrary-angle images with the intended scanner.
Verify the final image after printing or format conversion.

Java: Unit Class

Mon, 01 Jan 0001 00:00:00 +0000

Unit Class

Most size-related generation properties are represented by the Unit class. A Unit stores one physical value and exposes conversions to other units.

Set values in pixels

generator.getParameters().getBarcode().getXDimension().setPixels(3.0f);
generator.getParameters().getBarcode().getBarHeight().setPixels(100);

Pixel values are direct raster measurements and do not scale when the output resolution changes.

Set values in physical units

generator.getParameters().setResolution(300.0f);
generator.getParameters().getBarcode().getXDimension()
        .setMillimeters(0.33f);
generator.getParameters().getBarcode().getBarHeight()
        .setMillimeters(15.0f);

Physical values are converted to pixels according to the current resolution. Use updateResolution when working with a standalone Unit object or when inspecting a conversion explicitly.

Unit unit = new Unit();
unit.updateResolution(300.0f);
unit.setInches(0.25f);
float pixels = unit.getPixels();

Supported measurements

Common setters include:

setPixels
setMillimeters
setInches
setPoint
setDocument

Use physical units for printer-oriented layouts and pixels for fixed raster assets. Do not mix a fixed physical X-dimension with an auto-size mode that recalculates module size.

Complete example

View UseUnitExample.java

set

Java: Image and Layout Parameters

Mon, 01 Jan 0001 00:00:00 +0000

Image and Layout Parameters

Aspose.BarCode for Java provides image-level and layout-level parameters that control the generated canvas, barcode placement, automatic sizing, and conversion between physical units and pixels.

These settings are useful when a barcode must fit a predefined image area or match a target print resolution.

The complete source code for the examples in this article is available on GitHub:

View ImageAndLayoutParametersExample.java

Image parameters and barcode parameters

Generation settings are organized into several parameter groups.

Image-level settings are available directly from BaseGenerationParameters:

generator.getParameters().getImageWidth();
generator.getParameters().getImageHeight();
generator.getParameters().setResolution(300.0f);
generator.getParameters().setAutoSizeMode(AutoSizeMode.NEAREST);

Barcode-level settings are available through getBarcode():

generator.getParameters().getBarcode().getXDimension();
generator.getParameters().getBarcode().getBarHeight();
generator.getParameters().getBarcode().getPadding();

Image dimensions define the output canvas. Barcode dimensions define the geometry of the symbol inside that canvas.

Set the output image size

Use ImageWidth and ImageHeight to specify the generated bitmap dimensions.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "IMAGE-SIZE"
);

generator.getParameters()
        .getImageWidth()
        .setPixels(400);

generator.getParameters()
        .getImageHeight()
        .setPixels(160);

generator.save(
        "code128_image_size.png",
        BarCodeImageFormat.PNG
);

The image size includes the barcode, human-readable text, captions, padding, and border.

A canvas that is too small can force the barcode into an unsuitable layout or leave insufficient room for text and margins.

Configure automatic sizing

Use AutoSizeMode when the barcode must fit a predefined image box.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.QR,
        "AUTO-SIZE"
);

generator.getParameters()
        .getImageWidth()
        .setPixels(240);

generator.getParameters()
        .getImageHeight()
        .setPixels(240);

generator.getParameters()
        .setAutoSizeMode(AutoSizeMode.NEAREST);

generator.save(
        "qr_auto_size.png",
        BarCodeImageFormat.PNG
);

AutoSizeMode.NEAREST selects barcode dimensions that fit the specified image size while preserving valid symbol geometry as closely as possible.

This mode is useful for:

thumbnails;
fixed-size labels;
predefined UI placeholders;
generated reports;
bitmap templates.

Manual sizing and automatic sizing

Manual sizing and automatic sizing represent different layout strategies.

With manual sizing, you control barcode geometry directly:

generator.getParameters()
        .getBarcode()
        .getXDimension()
        .setPixels(3);

generator.getParameters()
        .getBarcode()
        .getBarHeight()
        .setPixels(80);

With automatic sizing, the library calculates effective dimensions to fit the requested image box:

generator.getParameters()
        .setAutoSizeMode(AutoSizeMode.NEAREST);

generator.getParameters()
        .getImageWidth()
        .setPixels(300);

generator.getParameters()
        .getImageHeight()
        .setPixels(100);

When automatic sizing is enabled, explicit X-dimension and bar-height values may no longer determine the final symbol size.

Use manual sizing when exact module width or bar height is required. Use automatic sizing when fitting the barcode into a target canvas is the primary requirement.

Configure output resolution

Use setResolution to define the output resolution in dots per inch.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "PRINT-READY"
);

generator.getParameters()
        .setResolution(300.0f);

generator.save(
        "code128_300dpi.png",
        BarCodeImageFormat.PNG
);

Resolution is especially important when dimensions are specified in physical units such as:

millimeters;
inches;
points.

For example:

generator.getParameters()
        .getBarcode()
        .getXDimension()
        .setMillimeters(0.33f);

generator.getParameters()
        .getBarcode()
        .getBarHeight()
        .setMillimeters(15.0f);

generator.getParameters()
        .setResolution(300.0f);

The resolution value determines how physical measurements are converted to pixels.

When image dimensions are already specified directly in pixels, increasing the resolution value does not by itself increase the bitmap width or height.

Create a fixed-size print-oriented image

The following example combines a target image box with a print resolution.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "PRINT-BOX"
);

generator.getParameters()
        .setResolution(300.0f);

generator.getParameters()
        .getImageWidth()
        .setPixels(500);

generator.getParameters()
        .getImageHeight()
        .setPixels(180);

generator.getParameters()
        .setAutoSizeMode(AutoSizeMode.NEAREST);

generator.save(
        "code128_print_box.png",
        BarCodeImageFormat.PNG
);

A fixed pixel box does not guarantee a specific physical barcode size unless the image is rendered or printed at the intended resolution.

Validate the final X-dimension, quiet zones, and print dimensions for the target application.

Configure padding within the image

Padding adds blank space around the barcode symbol inside the generated image.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "IMAGE-PADDING"
);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getLeft()
        .setPixels(20);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getRight()
        .setPixels(20);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getTop()
        .setPixels(10);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getBottom()
        .setPixels(10);

generator.save(
        "code128_image_padding.png",
        BarCodeImageFormat.PNG
);

Padding affects the available layout area. Large padding values leave less space for the symbol when a fixed image size is used.

Padding can reserve space for quiet zones, but the required quiet-zone dimensions depend on the symbology and application specification.

Account for human-readable text

Human-readable text requires additional vertical space.

generator.getParameters()
        .getBarcode()
        .getCodeTextParameters()
        .setLocation(CodeLocation.BELOW);

generator.getParameters()
        .getImageHeight()
        .setPixels(180);

If the image height is too small, the barcode or text can become compressed.

When using large fonts, captions, or increased text spacing, increase the image height accordingly.

Create a compact barcode image

To create a compact image:

hide human-readable text if it is not required;
reduce top and bottom padding;
set the target image dimensions;
enable automatic sizing.

BarcodeGenerator generator = new BarcodeGenerator(
        EncodeTypes.CODE_128,
        "COMPACT-LAYOUT"
);

generator.getParameters()
        .getBarcode()
        .getCodeTextParameters()
        .setLocation(CodeLocation.NONE);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getTop()
        .setPixels(1);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getBottom()
        .setPixels(1);

generator.getParameters()
        .getImageWidth()
        .setPixels(300);

generator.getParameters()
        .getImageHeight()
        .setPixels(60);

generator.getParameters()
        .setAutoSizeMode(AutoSizeMode.NEAREST);

generator.save(
        "code128_compact.png",
        BarCodeImageFormat.PNG
);

Compact barcodes should always be tested with the intended scanner and output medium.

Choose between pixels and physical units

Use pixels when:

the final output is a screen image;
exact bitmap dimensions are required;
the rendering environment is fully controlled.

Use millimeters or inches when:

the barcode is intended for printing;
physical dimensions must remain consistent;
the printer resolution is known.

Use points primarily for typographic values such as font size and text spacing.

Recommendations

Decide whether exact barcode geometry or exact image size is more important.
Use manual sizing for controlled X-dimension and bar height.
Use AutoSizeMode.NEAREST for fixed image boxes.
Set the intended resolution before using physical units.
Provide enough image space for text, captions, padding, and borders.
Do not assume that a fixed pixel image has a fixed physical size.
Validate compact and print-oriented layouts with the final scanner and printer.