Formatswap - Texture Converter

by Kuimi3D in Scripts and Addons

For better visualization, please see the documentation in the link bellow:

If you find any bug, please contact us in this link:


How to install

Just install the zip file in blender preferences

Where will the addon tab be?

In the sidebar of the node editor

First thing to do when installing the addon

Go to addon preferences and define a device for converting (If you have any problem when converting images, try to switch the device or render engine)

First and simple conversion

The addon is a complete tool for converting images, that is why a lot of panels will be closed when you load a new blend file. the panels that are not closed are the only panels you need to make a simple resize or conversion of selected textures.

For this first conversion, please create a new blend file, and load any texture in the default cube (or any object you have in this empty scene).

Don't forget to save this file! the addon needs the file to be saved before any conversion

We can starts from the top to the bottom:

1. Select Textures

Here is where you will be able to select the textures you want to resize or convert. 

All Objects: Will select all textures of objects in your scene

Selected Objects: Will select textures only in selected objects

Selected Material: Will select only textures in the select material (check the "Selected Nodes Only" to convert or resize only textures in selected nodes

For this first conversion, i recommend you to convert textures of the selected material only.

2. Keep Information

Here is where you will be able to select what information of each texture you want to keep, this will be the default setting to make a simple conversion, for now we just want to change the size and format of each texture.

If you uncheck all options, you will be able to change the color depth, and color channels of each texture (it will depends of the format you chose)

like in this example:

3. Converting Settings

Here you will be able to set the settings of the new textures you want, like the resolution, format and more

for now just change the resolution and the format you want

And it's done, just press the "convert textures" button, and wait a little bit. When finished, the textures will be in a folder called "Textures" in the same directory as your blend file.

Learning the complete power

Now you have learned how to make a simple conversion with FormatSwap, and now you will be learning everything that this addon has to offer.

In the simple converting process, we have ignored some panels and options that are not necessary for converting textures, but it's there if you need them!

Batch Converting

Batch Converting is a very useful feature if you have to convert a texture of one object or asset in different Sizes, all you have to do is to switch to "Batch Converting" , and add the variations of resolution you want in these textures.

Post Processing

Here you will be able to change some properties of the converted textures.

Remember that you can use the addon just to change the color of one texture, you don't necessarily have to change the size or format, to keep all the information of a texture, just check all options in the "Keep Information Panel", and you will be able to generate a new image just changing the color.

Selective Converting

Selective Converting is a very useful feature if you have a huge scene with a lot of textures, and you want to convert textures only if specific properties.

It is very simple to use, just select the selective method:

Convert Textures: Will convert only textures with selected properties bellow.

Ignore Textures: Will Ignore textures with selected properties bellow.

If you don't want any filters, just disable all

Critical Maps Detector

Some PBR maps cannot be converted or resized in the same way as other maps, here you will be able to deal with them.

Output Settings

A simple panel where you will be able to select the output folder of the textures, if you want the textures to be in the sabe blend file directory in the textures folder, just keep it checked.

Final Settings

Here is an important panel, where you will be able to change important settings of the conversion.

Auto Save File - Please always keep it active! for the conversion works as expected the blend file should be saved, because the conversion process will find only images that are saved in the blend file data, meaning that if you added a texture, and want to convert it, and the blend file does not have this texture saved in the file, the converter will not find it!

And when the file is saved before the converting, if you want to get back to your textures, you will be able to just re-open the file, and everything will get back to before the converting

Auto Toggle Console - With this option active, when the process starts, the console window will be opened. the console is the only place where you will be able to see the converting process, because blender will be freezed during the process

Note that if you are converting a lot of textures, blender will be freezed until all the process is done, and the only way to cancel it is to force blender to close.

In blender, addons can only toggle on/off the console, meaning that if already have the console opened, if this option is active, the console will be closed. So keep in mind that the console should be closed before the conversion starts (or just uncheck the box, and the console will not be toggle)

Auto Replace Textures - This is one of the most important options in the addon, if checked, when the conversion is finished, the addon will automatically replace each node of the old textures. if you don't want this to happen, just uncheck this box!

Auto Purge Images - With this option active, after the replacing process finished. the addon will purge all imagens in the blend file.

If this option is not enabled, in a scene with 150 textures, if you convert all of these textures, after the addon replaces all textures there will be 300 textures in your blend file, that will be deleted only when the blend file is closed.

Create Backup File - This is important if you want to get back to the version of the file before the converting and replacing process. a folder in the same original blend file will be created, and inside of it will be a blender file version before the replacing process, and you will be able to access it at any time!

Conversion Log

Everytime you make a conversion with FormatSwap, a log file will be created in the output folder, like in this gif bellow

File name: Conversion Result.txt

In the text file, you will be able to check if everything was converted and replaced as expected, if not, you will be able to check what could not be replaced or converted

Why sometimes this can happen?

The addon will works fine in the normal condition images,but sometimes "broken images" happens, like these examples bellow:

  • Blender does not support this file
  • The image texture was deleted or never existed
  • The texture is in a linked model
  • The texture name in blender is not the same as the original image
  • The original texture resolution is 0px
  • The image data is empty

If any of this happens in some texture in your scene, this information will be in the log file!

Addon Preferences

Render Device: Change the render device for converting

Render Engine: Change the render engine for converting

Default JPG Quality and Default PNG Compression 

Here you will be able to set the default setting for JPG Quality and JPG Compression, these default properties will be used when you activate "Keep Original Format"

Advanced Section - Change only if necessary

Console Mode

Here you will be able to change the information that will be displayed in the console.

Sleep Time Beetween Conversions

Here you can define a time in seconds between each conversion, this time is necessary for OS to compute new textures in the output folder

The perfect sleep time will depends on your hardware!

You can try yo reduce this sleep time if you have a more powerful hardware, or increase this sleep time if you have a slower hardware.

"How do i know if the sleep time is good or not?"

If the sleep time is not enough for your hardware, you will get some replacing texture errors in the console.

This happens because when the replacement process started, the OS did not had time to update each new texture in that folder.

OS Waiting Method

Here you will be able to change the wating method, this is where you will be able to define how many seconds the addon will wait for OS to update the texture folder.

Default Method: in this method, the addon will refresh the texture folder the number of seconds will selected bellow.

For example, lets put 10 seconds

If in 10 seconds, the texture folder still the same, the addon will start to replace the textures. If in 10 seconds the texture folder has a new image, it means that OS still updating this folder, so the addon will wait more 10 seconds until no changes happens in 10 seconds, and after that, the replacement process will starts.

Simple (Timer) Method: In this method, the addon will wait how many seconds you defined bellow, and after that, the replacement process will starts.

How to speed up the FormatSwap Converting process

By default, the advanced settings in the addon preferences are setted to FormatSwap run without errors in slower computers.

Please, read the topic above about these settings to fully understand this configuration!

If you have a good computer, you can set the settings to the one bellow:

In this setting, the addon will wait one seconds before each texture conversion, and after all textures converted, the addon will wait 15 seconds to the OS to update the output textures folder.

If you want to try a faster setup, you can set the settings to the one bellow:

With this setting, the conversion process will be a lot faster! the addon will not wait between each texture conversion, and after all textures converted, the addon will wait 15 for OS to update the output textures folder.

Remember that if you start to see replacing errors in the console, probably means that the addon is not waiting enough for OS to update the output textures folder.

Texture Replacer

In the FormatSwap Addon Tab, you will be able to find the texture replacer tool. You can use this to replace your own converted textures that blender could not find because the file extension has changed.

  1. Just select the selection method (All Objects, Selected Objects or Selected Material) 
  2. Select the format to find (the new extension of the files)
  3. Select the folder where the textures are
  4. And press the button

The addon will replace all old textures to the new textures with this new format, remember that the new textures should have the same name and only the extension sould be changed.

Material Restore

In the FormatSwap Addon Tab, you will be able to find the Material Restore tool. you can use this to restore a selected material to the old version before the conversion process.

But you have to have the FormatSwap backup folder with the FormatSwap Backup file in your blend file directory. this backup file is created when you start a new conversion.

You blend file directory:

Remember that this backup file creation process is automatic if you have "Create a Backup File" Enabled when starting a new conversion

If you have the backup file in a different folder, you can manually place it.

WARNING: If you make a new conversion after other, this backup file will be replaced!

Warning - Things you should know

The addon will not convert duplicated images

if you have two textures with the exact same name and extension, only one of these textures will be converted, you will be able to check what textures were duplicated and not converted in the log file.

In the most cases, duplicate textures will happen when you load the same material or textures twice, and if this is the case, you have no problem, is the same image, so when replaced, the converted images will be the same.