Part bin files
See the faq section for information on how to find the configuration location.
There are currently five kinds of files controlling the part bin content. These are:
- partBin.fav
- partBin.his
- partBinGroups.inf
- *.inv
- *.pbg
partBin.fav
partBin.fav located in the config folder holds your favorite parts in no particular order. Favorite parts can be made visible in the part bin by configuring part bin groups of the 'favorite' kind.
It's best not to edit this file out side LDCad. You can however just delete it, while LDCad is closed, if you want to clear your favorites. The file will be recreated on next program start up.
partBin.his
partBin.his located in the config folder holds your complete LDCad part usage history. Historic part use can be made visible in the part bin by configuring part bin groups of the 'history' kind.
It's best not to edit this file out side LDCad. You can however just delete it, while LDCad is closed, if you want to clear your history. The file will be recreated on next program start up.
partBinGroups.inf
partBinGroups.inf is a cache file used to keep the part bin tree up-to-date in relation to its pbg sources./p>
Do NOT edit this file as it is maintained by LDCad. You can however just delete it when needed. LDCad will regenerate it the next time you start the program resulting in the 'updating content...' message in the part bin window.
Inventory files (*.inv)
Inventory files are basically cache files containing selected header information from all LDraw (official/unofficial) library files currently available in LDCad.
Do NOT edit these files as they are maintained by LDCad. You can however just delete them when needed. LDCad will regenerate them the next time you start the program resulting in the 'updating content...' message in the part bin window.
part bin group files (*.pbg)
Part bin group files are used to configure the contents of the part bin window inside LDCad. This is done by supplying a pbg for each group in the part bin tree.
All *.pbg files are located in the partBin folder of your installation. At that location you will find a sysRoot.pbg and default subfolder. The default folder holds the official (default) part bin configuration. It is not recommended to edit the contents of that folder.
If you want to add / create custom part bin groups you should do so by adding second folder besides the default one. e.g. by coping and renaming it. Any such folder will be automatically processed / added to the bin if it has at least a root.pbg file inside it.
After you added a second folder with your modified pbg files to the partBin folder it will become visible in the part bin window by navigating to the part bin root. This root will now list the part bin folders instead of the default part bin root. This behavior will only be applied if there are multiple folders in the partBin folder. Other wise it will default to the single folders root group.
pbg files are plain text files which hold a collection of options and or items. The generic structure is like this:
[optionsSection]
option1=value
option2=value
option3=value
<itemsSection>
itemValue1
itemValue2
itemValue3
Basic group
The basic group is used to list hand picked items in the part bin view. Its basic structure is like so:
[options]
kind=basic
caption=Group caption
description=Short group description
picture=someRelImage.png
mascot=someItemFromTheItemsSection
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
<items>
item1
item2
item3
caption is used to define the short group name displayed at the top of Part bin views. It's best to keep this text at only a few words as the part bin is usally not very wide.
description is used to define the hint/help text displayed in the status bar whenever something below the mouse cursor has to do with this group.
picture is used to name an optional (texture) picture to be used in part bin cells whenever its item referees to this group. If this option is left empty the mascot will be used instead. The picture filename must be given relative to the pbg file location.
mascot is used to name a single item listed in the items section which will act like the mascot of the entire group. It will then be displayed in higher groups if one of its items references to this group. Mascots will only be used if the picture option is left empty. If both the mascot and picture options are left empty the first item in the list will be used as the mascot.
id is used to assign a (semi) unique id for this group so you can force a custom sorting order in higher referring groups.
sortOn must be set to none, name, description, id or timeStamp to indicate how the items must be sorted before displayed in the part bin window.
sortDesc must be set to true or false to indicate if the items must be sorted in reverse or not.
sortCaseInSens must be set to true or false to indicate if the items must be sorted case insensitive or not if sortOn is using a text based field.
The items section is used to supply the hand picked items (one per line) you want this group to display. See below for the format of items section lines.
Items section lines
Almost all pbg group files contain an items section. This section lists the items to be displayed in the part bin view's grid. Depending on the group kind item lists are ether static or generated. If generated the items section will be used more or less as a cache and should therefore not be edited. But if the list is static (like in the basic group) you need to understand the line format in order to add valid items to a group.
Unless otherwise stated in the group kind's documentation all items are ether a group reference (branches) or something peaceable (leaves).
Group references
References are recognized by not having an extension. To add a group reference to the items section you just need to state the groups pbg filename without the extension and relative to the sub part bin's root.phg file.
For example if you have the following structure of files in your part bin configuration folder:
root.pbg
groupA.pbg
groupB.pbg
sorted\main.pbg
sorted\groupC.pbg
sorted\groupD.pbg
Now to make all those groups accessible from the part bin you need to add references to them to the root.pbg file. This because the root.pbg file will always be used as the starting point in any sub part bin. To list all other groups you could setup root.pbg like so:
[options]
kind=basic
caption=My root
description=Testing group refs
picture=
mascot=
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
<items>
broupA
broupB
sorted\main
sorted\groupC
sorted\groupD
The notation for e.g. a groupD reference will always be the same no matter where the containing pbg group is located. So for example you could edit main.pbg to be something like this:
[options]
kind=basic
caption=Main
description=Testing sub group refs
picture=
mascot=
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
<items>
sorted\groupC
sorted\groupD
And then remove the groupC and groupD references from root.pbg so you will have created a standalone branch reachable from root.pbg. Remove the groups from root.pbg is not mandatory as the whole reason for the 'relative to' rule is so groups can be used multiple times and from any group.
So in short the location of pbg files does not really influence the part bin tree you setup using references. In practice it's best to only put pbg files in sub folders if they are in some way related to each other or represent a major sub tree in your bin configuration (like the sorted branch in the official bin).
Part references
Part references are recognized by having an extension in their items section line notation. They also allow optional extra information. A fully configured line looks similar to this:
3001.dat:[sourceInv=parts][color=15][count=12][ts=1424726318]
3001.dat is the LDraw file name for the part you want listed.
sourceInv is the place LDCad must look for the mentioned LDraw file. It must be set ether parts (the default) or templates.
color is the color you want the part to be displayed in, using color 16 (the default) will render the part in LDCad's current working color.
count can be used to indicate e.g. the number of brick of this kind present in a offical set or something. If above 0 it will be displayed in the parts cell. Future versions of LDCad will do more useful stuff with this property for now its only a FYI thing.
ts is used to supply a (platform depended) time stamp using a large integer number. This property is currently only used internally by LDCad to make the history group work like it does.
All [option=value] blocks are optional and only useful in certain situations so you will mostly be writing just the LDraw .dat names when listing parts in e.g. a basic pbg file. like for example editing groupA.pbg to be like so:
[options]
kind=basic
caption=Group A
description=Testing part listing
picture=
mascot=3003.dat
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
<items>
3001.dat
3002.dat
3003.dat
3004.dat
3005.dat
Filter group
Arguably one of the most important group kinds is the filter group. It can be used to generate item lists by filtering the inventory using a collection of rules. Its basic structure is like so:
[options]
kind=filter
caption=Group caption
description=Short group description
picture=someRelImage.png
mascot=someItemFromTheItemsSection
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
sourceInv=parts
<rules>
rules1
rules2
rules3
caption, description, picture, mascot, id, sortOn, sortDesc and sortCaseInSens have been discussed above and have the same meaning inside this file.
sourceInv is used to set select the inventory the filter must be used on. It must be set to ether parts or templates
The rules section is used to define the filter which will be applied upon the given source inventory. Every item in the source inventory will be tested against these rules. Depending on the rule kind and its condition items will be ether added or removed from a result set. When an item 'survives' all rules it will be displayed in this groups part bin grid.
Filter rule types
The filter rules are used to manipulate the result set for this group. In the beginning the set will be empty. By walking trough the rules on a per inventory item basis items can be added and removed from the result set.
The include rule is used to optionally add the currently processed inventory item to the result set. If the rule's condition is met the item will be added to the result set and the next rule will be evaluated, if the condition is not met it will not be added but the next rule will still be evaluated.
The exclude rule is used to optionally remove the currently processed inventory item from the result set. If the current inventory item is in the result set and the rule's condition is met it will be removed. If removed processing for this inventory item will be canceled and processing of the next one will begin.
The keep rule is used to optionally assign special status to the currently processed inventory item if it's already in the result set. If the rule's condition is met the item will remain in the result set no matter the conditions of the following rules.
The static rule is used to optionally force the currently processed inventory item in the result set. If the rule's condition is met the item will become part of the result set and can't be removed again by any following rule.
Filter rule conditions
Every rule has a condition, possible conditions are:
The all condition is always 'true'. It is used to e.g. initially set the result set to the entire source inventory.
The partName condition is used to test the inventory item using its LDraw partname. The part name will be tested against one or more (separated by ',') phrases. The '*' wild card is allowed before and or after a phrase to indicate it should match anything starting and or ending with the given text. By default phrases act like they are surrounded by the '*', e.g. '*3001*'.
The category condition is used to test the inventory item using its LDraw category text. The category will be tested against one or more (separated by ',') exact (case insensitive) category names.
The description condition is used to test the inventory item using its LDraw description text. The description will be tested against one or more (separated by ',') phrases. The '*' wild card is allowed before and or after a phrase to indicate it should match anything starting and or ending with the given text. By default phrases act like they are surrounded by the '*', e.g. '*brick*'.
The keyword condition is used to test the inventory item using its LDraw keywords. The keywords will be tested against one or more (separated by ',') exact (case insensitive) keywords until one of them matches.
The locKind condition is used to test the inventory item using its location information. The items location will be tested against a given location type. Possible types are: offLib (item is part of an official library), unOffLib (item is part of an unofficial library), lib (item is part of an official or unofficial library) or user (item is part of an user location).
The flags condition is used to test the inventory item against certain properties. Currently this can only be dirInRef which means it will match if the partName has a directory separator in its name (e.g. s\foo.dat)
Any rule condition can be inverted by prefixing a '!' to the condition kind keyword.
Filter rule examples
Above information might be very hard to grasp without some examples.
<rules>
include category technic
The filter has only one simple rule, all items must have the technic category tag.
<rules>
include category technic
exclude !description gear
An extension of the previous filter could be to just display the technic gears. This is done by removing everything that hasn't (notice the '!') got the phrase 'gear' in its description by means of the second rule.
<rules>
include partName 30*
include partName 40*
exclude partName 3001.dat
This will build a list of all parts starting with '30' (e.g. 3010.dat) and '40' but leaves out part 3001.dat.
<rules>
include category brick
exclude description ~*,_*,=*
exclude description duplo,spring
exclude !description pattern,pat.,sticker,logo
This will build a clean list of all patterned/printed bricks. the first rule includes all items in the bricks category. It then removes the special LDraw status items (~ means moved, _ means subpart, = means alias). Next it removes the non system bricks (duplo etc). And last it removes everything not having a phrase identifying it as patterned brick.
Folder list group
The folder list group is used to automatically list any pbg files located in a source folder. This makes it possible to add new bin branches without having to edit 'menu' groups. Its basic structure is like so:
[options]
kind=dirList
caption=Group caption
description=Short group description
picture=someRelImage.png
mascot=someItemFromTheItemsSection
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
listGroupsIn=someRelFolder
caption, description, picture, mascot, id, sortOn, sortDesc and sortCaseInSens have been discussed above and have the same meaning inside this file.
listGroupsIn names the folder from which the (pbg) content should automatically be listed. The folder name must be relative to the sub part bin root.pbg file location.
Category list group
The category list group is used to automatically generate a sub branch of group files, each listing items from a specific LDraw category. Its basic structure is like so:
[options]
kind=catList
caption=Group caption
description=Short group description
picture=someRelImage.png
mascot=someItemFromTheItemsSection
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
storeGroupsIn=someRelFolder
sourceInv=parts
[basicCatOptions]
sortOn=name
sortDesc=false
sortCaseInSens=true
<basicCatRules>
filterRule1
filterRule2
<rules>
filterRule1
filterRule2
caption, description, picture, mascot, id, sortOn, sortDesc and sortCaseInSens have been discussed above and have the same meaning inside this file.
storeGroupsIn is used to select a destination folder for the generated category groups. The name must be relative to the pbg file's location.
sourceInv is used to select the inventory you want to generate category groups for. It must be set to ether parts or templates
The category list group automatically generates filter groups for a selection of categories. The resulting pbg files will be placed at the storeGroupsIn location. Editing those resulting files in order to make tweaks is not possible as they are maintained by this group and thus will revert upon regeneration.
In order to have some additional control over the resulting filter groups defaults for the options and rules sections of those files can be set using the basicCatOptions and basicCatRules sections of this group.
You might want to set some additional group options and rules in those resulting file.The basicCatOptions section is used to set defaults for a number of pbg options (currently only sorting related ones) to be used in the options section of the generated filter group files.
The basicCatRules section is used to prefix a number of extra filter group rules to the rules section of the generated filter group files.
The rules section is used to filter the categories for which you want filter groups to be generated. Its mechanics are identical to the filter group rules. Its usage is just limited to the all and category condition kinds.
An example of a fully configured category group would be:
[options]
kind=catList
caption=Main categories
description=Parts sorted by LDraw category
picture=byCat.png
mascot=
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
storeGroupsIn=cats
sourceInv=parts
[basicCatOptions]
sortOn=name
sortDesc=false
sortCaseInSens=true
<basicCatRules>
exclude description ~*,_*,=*
<rules>
include all
exclude category moved
Favorites group
The favorite group is used to display the contents of the partBin.fav configuration file in the part bin window. Its basic structure is like so:
[options]
kind=favorites
caption=Group caption
description=Short group description
picture=someRelImage.png
mascot=someItemFromTheItemsSection
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
caption, description, picture, mascot, id, sortOn, sortDesc and sortCaseInSens have been discussed above and have the same meaning inside this file.
History group
The history group is used to display (part) of the contents of the partBin.his configuration file in the part bin window. Its basic structure is like so:
[options]
kind=history
caption=Group caption
description=Short group description
picture=someRelImage.png
mascot=someItemFromTheItemsSection
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
timeFrame=7
splitOnColor=false
caption, description, picture, mascot, id, sortOn, sortDesc and sortCaseInSens have been discussed above and have the same meaning inside this file.
timeFrame is used to indicate how many days this group must look back while generating the item list.
splitOnColor must be set to true or false to indicate if historic parts should be displayed using the color used (true) or just be listed (grouped) in their neutral (16) color (false).
Overview group
The overview group is used to display a collection of dynamic items. Items which are depended on e.g. the current model being used inside LDCad. This can then be used to display e.g. all used parts etc Its basic structure is like so:
[options]
kind=overview
caption=Group caption
description=Short group description
picture=someRelImage.png
mascot=someItemFromTheItemsSection
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
showColors=false
showCounts=false
<rules>
rule1
rule2
rule3
caption, description, picture, mascot, id, sortOn, sortDesc and sortCaseInSens have been discussed above and have the same meaning inside this file.
showColors must be set to true or false to indicate if the resulting items should split parts based on their colors or if they should just be listed once in their neutral (16) color.
showCounts must be set to true or false to indicate if the resulting items should display (usage) counts in their part bin view cells or not.
The rules section is used to build the wanted result set using the familiar filter rules types we discussed in the filter group chapter. We'll only be using a different set of conditions while defining overview filter rules.
Overview filter rule conditions
Overview filter rule conditions are currently not where I would like them to be so a near future version of LDCad will probably change (some of) these conditions meanings.
all matches everything / is always true.
models matches all model items currently loaded.
parts matches all related parts in all currently loaded models.
curFileContent matches all parts/models defined in the currently active file.
curStepContent matches all parts/models used in the current step of the currently active model.
curStepDeps matches all parts/models recursively used in current step of the currently active model.
curModelDeps matches all parts/models recursively used in current active model.
Overview filter rule examples
Some examples:
<rules>
include curFileContent
exclude !models
This will show the models (but not the parts) defined in the currently active model's file.
<rules>
include curStepDeps
exclude models
This will show all (recursively) used parts of the currently active step.
Tools group
The tools group is used to display (some of) the special LDCad specific parts like markers, spring and path configuration meta's. Its basic structure is like so:
[options]
kind=tools
caption=Group caption
description=Short group description
picture=someRelImage.png
mascot=someItemFromTheItemsSection
id=0
<items>
item1
item2
caption, description, picture, mascot and id have been discussed above and have the same meaning inside this file.
Tool group items
The tool group behaves similar to the static group, the only difference is it uses a different format for the item lines. The only items allowed are special tool identifiers, namely:
The marker identifier adds a LDCad marker meta to the items list. An optional [temp=value] parameter can be given to select if the marker should be temporary or not. The value for temp must be ether true or false.
The pathPoint identifier adds a path point meta to the items list. An optional [type=value] parameter can be given to select the point type. The value for type must be ether bezier or circle.
The pathAnchor identifier adds a path anchor meta to the items list.
The pathSkin identifier adds a path skin meta to the items list.
The springPoint identifier adds a spring point meta to the items list.
The springSection identifier adds a spring section meta to the items list.
The springAnchor identifier adds an anchor anchor meta to the items list.
The following items section will result in a tool group containing all items needed to build custom path content.
<items>
pathPoint [type=bezier]
pathPoint [type=circle]
pathSkin
pathAnchor
Search group
The search group can be used by the user to search the LDraw inventories. Its basic structure is like so:
[options]
kind=search
caption=Group caption
description=Short group description
picture=someRelImage.png
mascot=someItemFromTheItemsSection
id=0
sortOn=name
sortDesc=false
sortCaseInSens=true
caption, description, picture, mascot and id have been discussed above and have the same meaning inside this file.
System root group
Now you somewhat more familiar with the pbg file configuration it might also be interesting to know the inner workings of the absolute top level sysRoot.pbg.
It is not recommended to edit this group file as it is part of the LDCad default installation and there fore overwritten during upgrades. If you need to edit it for any reason just make notes of your changes so you can reapply them after upgrades. The pbg file has the following structure:
[options]
kind=sysRoot
caption=Group caption
description=Short group description
picture=someRelImage.png
mascot=someItemFromTheItemsSection
id=0
sorted=true
sortInsens=true
<ignore>
someFolderName1
someFolderName2
caption, description, picture, mascot and id have been discussed above and have the same meaning inside this file.
The sorted value must be ether true or false indicating if the folder list should be sorted or not.
If sorted the sortInsens must be ether true or false indicating if the folder list should sort case insensitive or not.
The ignore section is use to list folders you don't want to be part of the color bin menu (even if they have a root.pbg). You can use this list to mask out e.g. old versions or prototypes etc.