Author Topic: Color Binning Tool  (Read 4706 times)

0 Members and 1 Guest are viewing this topic.

Offline miros1

  • Face Collector
  • Administrator
  • Whippy Whippersnapper
  • *****
  • Posts: 3697
  • Gender: Female
  • Face Collector
    • The Wooden Simolean
Color Binning Tool
« on: October 16, 2012, 01:45:33 PM »

This plugin allows you to categorize your hair package files so that they will appear in the correct color bins in the game catalog. You can also select which PropertySets you wish to keep or remove from the output packages.

The inspiration and indeed most of its logic is stated in the Recategorising hair with SimPE thread.
If you're new to MATY, please delight yourself with the MATY F.A.Q.

If you wish to give your feedback, you can email me, or use the tool's forum threads at MATY and MTS 2.

I would like to thank everyone that contributed with a bit of knowledge that was used in this tool.

Offline miros1

  • Face Collector
  • Administrator
  • Whippy Whippersnapper
  • *****
  • Posts: 3697
  • Gender: Female
  • Face Collector
    • The Wooden Simolean
Installation, Basic usage and Credits
« Reply #1 on: October 16, 2012, 01:46:26 PM »

The color binning tool is a custom plugin for SimPE.

Its purpose is to change custom hair packages so that custom hair recolors appear in the standard color bins.

It was designed to be easy to use: on each standard color tab, you can load a hair package file; after you load the four packages into their respective bins, you can save the result.

There is no need to edit any PropertySet, as the binning logic is already done for you.

More information and some tutorials can be found in the plugin's website:

    Extract the file theos.gbct.plugin.dll

    Copy it into SimPE's Plugins folder, which in a default installation is at C:\Program Files\SimPE\Plugins

    Run SimPE and verify that you have a menu item named "Color Binning Tool" under SimPE's Tools menu.

Basic Usage

After the plugin is installed, start SimPE.

On the Tools menu, click on the "Color Binning Tool" item, and the plugin's main window should appear. Initially, the "Black" color tab is selected by default.

Use the "Package" menu or the context menu to load a package file into the selected tab. Repeat this process for the other tabs (Brown, Blond and Red).

You can select which age groups you wish to keep or remove on each color tab. You must pay special attention to the fact that a properly binned hair should have only one elder (grey) recolor, so you must choose carefully one elder recolor out of the four available.

On most cases you can ignore the Grey and Custom tabs, so you may proceed to review the package options (available in the menu Package->Options), and finally save the resulting package files.

I would like to thank to everyone that contributed to this project, and in particular to Motoki, for giving the momentum that started this project; Pinhead, whose invaluable knowledge put the code right on track again; and of course all the folks at MATY that were willing to test the plugin on its early stages.

Offline miros1

  • Face Collector
  • Administrator
  • Whippy Whippersnapper
  • *****
  • Posts: 3697
  • Gender: Female
  • Face Collector
    • The Wooden Simolean
Step-by-step example
« Reply #2 on: October 16, 2012, 01:47:23 PM »
Color binning session example

This step-by-step walkthrough attempts to show a typical color binning session.

It has been broken down to four steps: Examining the downloaded hair, Basic tool usage, Selecting the Grey recolor, Reviewing Options and Saving

In this example, we're going to use Plicka's Long Female Hair (downloadable from MTS2).

The first version of this document didn't contain these words, but I think it is important to make it clear: I don't use this example with the intention of disparaging the creator's work. The main problem arises from the fact that all creators use an incomplete tool (ie BodyShop), that does not allow the correct binning of recolors in the first place.
Step 1: Examining the downloaded hair.

If you already know what recolors you want to keep, proceed to Step 2.

As the creator didn't have time to put the recolors in the correct color bins, that burden falls now on us.

So we'll open BodyShop, and see what we can do.

Here is the blond recolor for the adult age: Screenshot of the chosen blond hair for the Adult age group, as shown in BodyShop.

We can already notice something wrong: changing to blond hair makes the brows change to black! But the tool will automatically take care of that :)

Next, the same blond hair for the elder age: Screenshot of the chosen blond hair for the Elder age group, as shown in BodyShop.

Again another annoyance: The elder hair catalog is filled with copies of elder textures, and in this case, the creator didn't even used a really grey color.

So the plan of action is to leave just one grey recolor.

The catalog for the teen age:
Screenshot of the catalog swatch of the chosen blond hair for the Teen age group.

We can see that it contains a new texture for a standard Maxis hair mesh, so we might as well remove the recolors, but the decision is all up to you.

The same applies to the child and toddler hairs, so if you really like the recolor you can keep it, otherwise it's better to remove the duplicates from the catalog (as we're going to show in the next step).
Screenshot of the catalog swatch of the chosen blond hair for the Child age group.Screenshot of the catalog swatch of the chosen blond hair for the Toddler age group.
Step 2: Using the tool.

Start the tool by using SimPE's menus Tools > Color Binning Tool. SimPE will begin to load the FileTable, so it may take a while before you can load any package.

After starting the tool, we can see there is a Tabstrip with the names of the colors.

Each tab can hold one package file.

All we have to do now is to load the package files into the correct color tabs!

In the selected color tab, use the menus to Open a Package.

A file select dialog will appear: Screenshot of the Open file dialog.

Althoug sometimes it's impossible to know what file contains the desired color, in this example the color can be easily discerned.

Now that we opened the file we can select which recolors we will keep.

But wait! Oh noes, with all the haste we mistakingly put the blond recolor in the Black bin!

That's where the "Move To" function comes handy, allowing us to correct the blunder. Screenshot showing how to move the selected package to another color tab, by means of the Move To menu item.

After that mishap, we can load the black color file into the Black color tab.

To remove an age group from a package, simply uncheck the respective item. Screenshot showing how age groups are included or excluded from the output.

As we had decided to remove the toddler and child recolors, uncheck the items accordingly.

So all you have to do is to repeat this process for the other colors:

    Select color tab
    Open respective package file
    Check desired recolors.

Step 3: Selecting the Grey recolor.

This is a matter that has caused so much confusion, that it deserves a step for it!

Remember when we saw in Step 1 that the elder age group had also four recolors for it?

When correctly binned, the hair must have only one grey recolor, so we'll select just one of the four available.

That's why the tool automatically unchecks the elder recolor items in normal color tabs, so that you can simply check the desired grey recolor, instead of unchecking three.

In our example, we don't have a really grey color. So we'll select the one that most closely matches a grey hair: the blond one. Screenshot of the elder recolor being selected in the Blond color tab.

Of course you will query: What about the Grey tab?

Well, if someone made a new recolor package with grey or white tones available for download, we could simply add the file to the Grey tab and uncheck the grey items from the normal colors.

In our example however, no such file is available, so we'll leave it empty.
Step 4: Reviewing Options and Saving.

Open the Options dialog. Each tab shows the relevant options for that category.

Package Settings: Screenshot of the Package preferences panel in the Options dialog.

    Guid: In this field you can review the family guid for the loaded packages. Recolors of hairtones should have the same family guid so that the game catalog will keep the same item selected when changing the hair color. You can click the link button to generate a new guid, or you can edit it manually. It will be automatically applied to the output packages.
    Text: Here you can set the tooltip that is displayed in the catalog (English only).
    Hide From Catalog: This is a global setting that will apply to all loaded packages. It has the same effect as unchecking all recolor items plus setting a flag in the Hairtone Xml (if applicable). It will not remove any referenced resources in the package.

Output Settings: Screenshot of the Output preferences panel in the Options dialog.

    Disable Source Packages: When checked, the package files that were used in the session will have its extension changed to .packagedisabled, so that they won't cause conflict with the newly generated packages. If you are absolutely and positively sure that you don't need the files anymore, you can delete them move them to a backup folder.
    Generate Single Package: Instead of creating a package file for each color, the tool can create one package with all the colors. It's recommended that this option is used only when creating the final package; On test runs, it's better to create a file for each color, so that it will be easier to load them again into the tool.
    Remove Unchecked Recolors: * It is recommended that you leave this option off *
    When checked, the unselected recolors are actually removed from the output packages, otherwise they'll simply be hidden from the catalog. Note that this setting is overriden by the Hide From Catalog setting.
    Compress Textures: Check this option to keep the file size within reasonable limits. Compressing textures will slow down the file save process, and might not work with all the textures.

Hairtone Settings: Screenshot of the Hairtone preferences panel in the Options dialog. This panel is only visible after you load the first hairtone package.

    Proxy for Custom Colors: Select the base color perceived by the catalog, that is applied to the packages loaded into the "Custom" tab.
    Hat: When checked, the resulting hair will be considered as a hat, mainly for turn-on/turn-off calculations in the game.

After you done all this work, it's now time to save it. On the Package menu, choose "Save As", and a file select dialog will appear. Screenshot of the Save file dialog.

Choose the base name for the output packages.

The color name will be appended to each package's filename, unless you checked the "Generate Single Package" option. Screenshot of Windows Explorer showing the generated output packages.

Open BodyShop and you should see the hair in the correct color bins.

Offline miros1

  • Face Collector
  • Administrator
  • Whippy Whippersnapper
  • *****
  • Posts: 3697
  • Gender: Female
  • Face Collector
    • The Wooden Simolean
Known Bugs/Issues
« Reply #3 on: October 16, 2012, 01:48:05 PM »
List of Known Bugs/Issues

This is a list of bugs and annoyances found in the tool so far, ordered by decreasing severity.

    If you choose to keep the original filenames, you should turn off the "Backup packages" options, or the tool will generate an error when saving the packages, and the output may be truncated (empty).
    Some texture resources may refuse to compress even if Texture Compression is specified. There is no workaroud for this problem.
    The tooltip Text setting in the Options panel only affects the English language.
    The options dialog may become hidden by the main form, and cannot be focused using either Alt+Tab or Alt+Esc. Workaround: move the main form so that the options dialog can show again.
    A recolor's mesh list may contain items with the text <not found in FileTable>. This happens because a recolor is referencing a custom mesh that is not in SimPE's FileTable. To correct this, add your custom hair/body/clothing meshes to SimPE's FileTable.
    When selecting a recolor item, the Properties panel may briefly switch between enabled and disabled state.

Offline miros1

  • Face Collector
  • Administrator
  • Whippy Whippersnapper
  • *****
  • Posts: 3697
  • Gender: Female
  • Face Collector
    • The Wooden Simolean
Change Log
« Reply #4 on: October 16, 2012, 01:48:53 PM »
Change Log
2007.12.26 (

    Code update for the new version of SimPe. SimPe should no longer warn about an obsolete method call.
    Added a few more values to the OutfitType enumeration.

2006.11.16 (

    Bugfix: A "subtype" property was erroneously being added to the PropertySet resources.
    Updated the Properties tab.

2006.11.14 (

    Bugfix: An error would occur when closing SimPe while the tool was still active.
    Updated the Properties tab.
    Small bugfix for the package backup function.

2006.11.13 (

    Added option to keep the original package names instead of renaming all packages. When this option is checked, the file save dialog will no longer appear, unless the "Generate Single Package" option is selected.
    Added tooltip for individual PropertySet items showing the original hairtone value.

2006.11.08 (

    Added backward-compatibility fix for packages created with the Pets EP (thanks to marvine).

2006.05.12 (

    The mesh list now displays each mesh package's file name.
    Added the Properties tab for recolor items.
    Enabled editing of the recolor items name. Note that for hair packages this name will also be renamed automatically using the tab's color name.
    The neighborhood options panel will show only when editing hair packages.
    Removed the restriction that disallowed loading more than one skintone package.

2006.05.09 (

    Bugfix: The 'Move To' list was not synchronized with the tabs contents.

2006.05.05 (

    Bugfix: The family guid was not applied to TextureOverlay packages.
    Disabled compiler optimizations for the dll file.

2006.05.03 (

    The mesh list is no longer cleared when the session resets.
    Added neighborhood DNA correction function: The custom hair guid's will be replaced by the respective standard guid on the selected neighborhoods (requested by silvertreedrake).

2006.05.02 (

    Added support for MeshOverlay property sets.
    Bugfix: The flags value for the "Hat" option was not correct (and to this day I still don't know if it's correct :P).

2006.04.26 (

    Bugfix: Output files no longer remain write-locked by SimPe.

2006.04.24 (

    Bugfix: When changing a material texture, the selected item would change to the first of the list.

2006.04.23 (

    Bugfix: An error occured when looking for a non-existent settings file (reported by Solowren).

2006.04.20 (

    Bugfix: The plugin could not load packages that had no tooltip description resource (reported by Solowren).
    Bugfix: After moving a package to a different color tab, the wrong genetic color would be assumed when using the "Revert to base texture" function.

2006.04.19 (

    Minor cosmetic fixes.

2006.04.18 (0.2.14/15.1)

    The main menu options are available according to the session state.
    When a mesh is applied to a recolor item, a visual indication of the change is shown.
    Bugfix: The "Load Mesh" function wasn't always available.
    Bugfix: The output options weren't being saved before a session reset (New Session).
    The automatic selecting/deselecting of elder age recolors is now applied on Hairtone and TextureOverlay packages only.
    The tool tries to prevent loading more than one skintone package per session, as setting the same family guid on multiple skintone packages yielded unwanted results.

2006.04.17 (

    The Texture Format option has been removed. It was both unnecessary and a source of possible confusion.
    The texture preview has been fixed (again). It can now correctly show the textures from outside packages, as long as they are referenced by the FileTable.
    The user's output preferences are now maintained between sessions, and saved in the SimPe's plugin data storage folder (\Data\Plugin).

2006.04.13 (0.2.11/12.1)

    Added the option to specify the texture format when texture compression is specified.
    Change the Load Mesh behavior: a mesh will only be applied when the "Apply Mesh" function is selected.
    When loading mesh packages with more than one mesh, all meshes will be displayed in the "Apply Mesh" list.

2006.04.10 (

    Bugfix: When reverting to a material's base texture of a grey recolor in a normal color bin, the color name was being used instead of 'grey'.
    Changed the texture output format to DXT3 when Texture Compression setting is on.

2006.04.07 (

    Bugfix: The texture compression setting wasn't being applied when selecting the "Generate Single Package" option (reported by Pinhead).
    Added option to select a mesh package for a recolor item. It will simply replace the resource references in the respective 3IDR file.
    Improved performance to the texture preview functions.
    The manipulations in the hairtone field are applied only for hair and texture overlay packages. This will allow PropertySet changes in other package types without changing that field.


    Added option to specify whether the package textures are compressed (global output setting).
    Bugfix: The tool was discarding the textures referenced by the stdMatNormalMapTextureName property in the material definitions (reported by idtaminger).
    Bugfix: When reverting to the MaterialDefinition base texture for a package in the "Custom" tab, the string "custom" was being added to the texture name (reported by Pinhead). The original name from the FileList will be used now.
    Bugfix: The "Hide From Catalog" option wasn't correctly overriding the "Remove Unchecked Recolors" option.
    Corrected the hairtone value applied to PropertySets for the elder age group in the "Custom" tab (thanks to Pinhead).


    The materials list is now automatically updated when the content changes.
    A texture reference can be copied to another color package, as requested by Motoki and Pinhead.
    The texture preview tries to find a texture in the FileTable.
    Added option to specify whether a hair package is hidden from the catalog (global package setting).
    Added option to specify whether a hair package is a hat (global hairtone setting).


    Bugfix: The "Use base texture" command in the Materials list wouldn't work if the resource had no entries in the filelist.
    Bugfix: The same package file could not be loaded into different color tabs.
    The tool tries to maintain package type integrity: the first package to be loaded determines the working mode - either Hairtone or TextureOverlay, and all following packages must be of the same type, otherwise a warning dialog will inform the user of the discrepancy.
    The previous change is reflected in the options dialog: the relevant options are available only when a matching package type is loaded.


    Bugfix: Changes to PropertySets and MaterialDefinitions weren't commited if the item was unchecked.
    Bugfix: Unused textures are again being removed from the package.
    Bugfix: The options dialog changes could not be cancelled.
    Added option to specify the proxy color for custom hairtones (requested by pioupiou).
    Minor UI changes to the options dialog.


    Added workaround for a known .NET Framework bug.
    The default state for the "Remove Unchecked Recolors" option is now off.
    PropertSets marked with the HideFromCatalog flag can now be re-enabled.


    Fixed a file locking bug when disabling the source packages.
    Corrected the value that was being set to a PropertySet flags, in order hide it from the catalog (thanks to Pinhead).
    Added feature that allows packages to be moved between color bins (thanks to Theo).
    Changed the tool's name.


    Added option to specify how deleted recolors are processed (Motoki/Pinhead mode).
    The option "Generate Single Package" works now.
    Added special treatment for elder hair recolors (thanks to Pinhead).


    The three main panels can now be resized using not-so-visible splitters.
    Fixed bug that prevented the plugin to load more than once.