color_tools.filament_palette

Filament palette management for 3D printing color matching.

This module provides classes and functions for managing 3D printing filament databases, with support for: - Maker-based filtering and synonym resolution - Material type and finish filtering (PLA, PETG, Matte, Glossy, etc.) - Color distance matching with multiple metrics - Owned filaments tracking for personalized recommendations - User extensions via user-filaments.json

The FilamentPalette class offers indexed lookups (O(1)) for maker/type/finish filtering, followed by perceptually accurate nearest-neighbor searches in LAB color space.

class color_tools.filament_palette.FilamentRecord(id, maker, type, finish, color, hex, td_value=None, other_names=None, source='unknown.json', hex2=None)[source]

Bases: object

Immutable record representing a 3D printing filament.

Filament colors are pre-computed in all major color spaces for fast matching. Supports dual-color filaments (some have primary and secondary colors).

The other_names field allows for alternative color names that can be used to find this filament.

The source field tracks which JSON file this filament came from (‘filaments.json’ for core data, ‘user-filaments.json’ for user additions). When there are conflicts (e.g., same RGB from multiple sources), user data takes priority.

Parameters:

  • id (str) – Unique identifier for this filament (e.g., “bambu-lab_pla-matte_jet-black”)

  • maker (str) – Manufacturer name (e.g., “Bambu Lab”)

  • type (str) – Material type (e.g., “PLA”, “PETG”, “ABS”)

  • finish (Optional[str]) – Surface finish (e.g., “Matte”, “Glossy”, “Silk”). Optional.

  • color (str) – Human-readable color name (e.g., “Jet Black”)

  • hex (str) – RGB color in hex format (e.g., “#000000”)

  • td_value (Optional[float]) – Transmission density value (0.0-1.0) for light transmission simulation. Optional.

  • other_names (Optional[List[str]]) – Alternative names this filament is known by. Optional.

  • source (str) – Source JSON file this record came from (auto-set during loading)

  • hex2 (str | None)

id: str
maker: str
type: str
finish: str | None
color: str
hex: str
td_value: float | None = None
other_names: List[str] | None = None
source: str = 'unknown.json'
hex2: str | None = None
__post_init__()[source]

Compute derived color representations in all color spaces.

Return type:

None

rgb: Tuple[int, int, int]
lab: Tuple[float, float, float]
__str__()[source]

Return a human-readable string representation of the filament.

Return type:

str

color_tools.filament_palette.load_filaments(json_path=None)[source]

Load filament database from JSON files (core + user additions).

Loads filaments from both the core filaments.json file and optional user/user-filaments.json file in the data directory. Core filaments are loaded first, followed by user filaments.

Parameters:

json_path (Path | str | None) – Path to directory containing JSON files, or path to specific filaments JSON file. If None, looks for filaments.json in the package’s data/ directory.

Return type:

List[FilamentRecord]

Returns:

List of FilamentRecord objects (core filaments + user filaments)

color_tools.filament_palette.load_maker_synonyms(json_path=None)[source]

Load maker synonyms from JSON files (core + user additions).

Loads synonyms from both the core maker_synonyms.json file and optional user/user-synonyms.json file in the data directory. Synonyms are merged, with user additions extending or replacing core synonyms per maker.

Parameters:

json_path (Path | str | None) – Path to directory containing JSON files, or path to specific maker_synonyms JSON file. If None, looks for maker_synonyms.json in the package’s data/ directory.

Return type:

Dict[str, List[str]]

Returns:

Dictionary mapping canonical maker names to lists of synonyms

color_tools.filament_palette.load_owned_filaments(json_path=None)[source]

Load owned filament IDs from JSON file.

Loads a list of filament IDs that the user owns from owned-filaments.json. This file is optional - if it doesn’t exist, an empty set is returned.

The JSON format is:

{
    "owned_filaments": ["id1", "id2", "id3"]
}
Parameters:

json_path (Path | str | None) – Path to directory containing owned-filaments.json, or path to specific owned filaments JSON file. If None, looks for owned-filaments.json in the package’s data/ directory.

Return type:

Set[str]

Returns:

Set of owned filament IDs (empty set if file doesn’t exist)

color_tools.filament_palette.save_owned_filaments(owned_ids, json_path=None)[source]

Save owned filament IDs to JSON file.

Saves the list of owned filament IDs to owned-filaments.json.

Parameters:

  • owned_ids (Set[str]) – Set of filament IDs to save

  • json_path (Path | str | None) – Path to directory for owned-filaments.json, or path to specific file. If None, saves to package’s data/ directory.

Return type:

None

class color_tools.filament_palette.FilamentPalette(records, maker_synonyms=None, owned_filaments=None)[source]

Bases: object

Filament palette with multiple indexing strategies for fast lookup.

Similar to Palette, but designed for 3D printing filaments which have additional properties (maker, type, finish) that we want to search by.

The indices allow for fast filtering: “Show me all Bambu Lab PLA Matte filaments” becomes a simple dictionary lookup instead of scanning the whole list! 📇

Supports maker synonyms: you can search for “Bambu” and it will find “Bambu Lab” filaments automatically.

Parameters:

  • records (List[FilamentRecord])

  • maker_synonyms (Optional[Dict[str, List[str]]])

  • owned_filaments (Optional[Set[str]])

classmethod load_default()[source]

Load the default filament palette from the package data.

Convenience method for quick loading without worrying about paths. Also loads maker synonyms and owned filaments automatically.

Auto-detects owned filaments: If owned-filaments.json exists and contains IDs, owned filtering will be the default behavior in filter/nearest methods.

Return type:

FilamentPalette

find_by_maker(maker)[source]

Find all filaments by a single maker or a list of makers.

Supports synonyms: searching for “Bambu” will find “Bambu Lab” filaments.

Parameters:

maker (Union[str, List[str]]) – A single maker name (str) or a list of names (can use synonyms).

Return type:

List[FilamentRecord]

Returns:

A list of all matching FilamentRecord objects.

find_by_type(type_name)[source]

Find all filaments by a single type or a list of types.

Parameters:

type_name (Union[str, List[str]]) – A single filament type (str) or a list of types.

Return type:

List[FilamentRecord]

Returns:

A list of all matching FilamentRecord objects.

find_by_color(color)[source]

Find all filaments by color name (case-insensitive).

Return type:

List[FilamentRecord]

Parameters:

color (str)

find_by_rgb(rgb)[source]

Find all filaments by exact RGB match, with user filaments prioritized.

Return type:

List[FilamentRecord]

Parameters:

rgb (Tuple[int, int, int])

find_by_finish(finish)[source]

Find all filaments by a single finish or a list of finishes.

Parameters:

finish (Union[str, List[str]]) – A single filament finish (str) or a list of finishes.

Return type:

List[FilamentRecord]

Returns:

A list of all matching FilamentRecord objects.

filter(maker=None, type_name=None, finish=None, color=None, owned=None)[source]

Filter filaments by multiple criteria.

This is like SQL WHERE clauses! Start with all records, then filter down by each criterion that’s provided. Maker, type, and finish can accept a single string or a list of strings.

Supports maker synonyms: filtering by “Bambu” will include “Bambu Lab”.

Auto-detects owned filtering: If owned-filaments.json exists with IDs, defaults to owned filaments only unless owned=False is explicitly passed.

Parameters:

  • maker (Union[str, List[str], None]) – A maker name or list of maker names (can use synonyms).

  • type_name (Union[str, List[str], None]) – A filament type or list of types.

  • finish (Union[str, List[str], None]) – A filament finish or list of finishes.

  • color (Optional[str]) – A single color name to match (case-insensitive).

  • owned (Optional[bool]) – Filter to owned filaments only. None (default) = auto-detect, True = owned only, False = all filaments.

Return type:

List[FilamentRecord]

Returns:

A list of FilamentRecord objects matching the criteria.

nearest_filament(target_rgb, metric='de2000', *, maker=None, type_name=None, finish=None, owned=None, cmc_l=2.0, cmc_c=1.0)[source]

Find nearest filament by color similarity, with optional filters.

The killer feature for 3D printing! “I want this exact color… what filament should I buy?” 🎨🖨️

Auto-detects owned filtering: If owned-filaments.json exists with IDs, defaults to searching owned filaments only unless owned=False is explicitly passed.

Parameters:

  • target_rgb (Tuple[int, int, int]) – Target RGB color tuple.

  • metric (str) – Distance metric - ‘euclidean’, ‘de76’, ‘de94’, ‘de2000’, ‘cmc’.

  • maker (Union[str, List[str], None]) – Optional maker name or list of names to filter by. Use “*” to ignore filter.

  • type_name (Union[str, List[str], None]) – Optional filament type or list of types to filter by. Use “*” to ignore filter.

  • finish (Union[str, List[str], None]) – Optional filament finish or list of finishes to filter by. Use “*” to ignore filter.

  • owned (Optional[bool]) – Filter to owned filaments only. None (default) = auto-detect, True = owned only, False = all filaments.

  • cmc_l (float) – Parameters for CMC metric.

  • cmc_c (float) – Parameters for CMC metric.

Return type:

Tuple[FilamentRecord, float]

Returns:

(nearest_filament_record, distance) tuple.

nearest_filaments(target_rgb, metric='de2000', count=5, *, maker=None, type_name=None, finish=None, owned=None, cmc_l=2.0, cmc_c=1.0)[source]

Find nearest N filaments by color similarity, with optional filters.

Similar to nearest_filament but returns multiple results sorted by distance.

Auto-detects owned filtering: If owned-filaments.json exists with IDs, defaults to searching owned filaments only unless owned=False is explicitly passed.

Parameters:

  • target_rgb (Tuple[int, int, int]) – Target RGB color tuple.

  • metric (str) – Distance metric - ‘euclidean’, ‘de76’, ‘de94’, ‘de2000’, ‘cmc’.

  • count (int) – Number of results to return (default: 5, max: 50)

  • maker (Union[str, List[str], None]) – Optional maker name or list of names to filter by. Use “*” to ignore filter.

  • type_name (Union[str, List[str], None]) – Optional filament type or list of types to filter by. Use “*” to ignore filter.

  • finish (Union[str, List[str], None]) – Optional filament finish or list of finishes to filter by. Use “*” to ignore filter.

  • owned (Optional[bool]) – Filter to owned filaments only. None (default) = auto-detect, True = owned only, False = all filaments.

  • cmc_l (float) – Parameters for CMC metric.

  • cmc_c (float) – Parameters for CMC metric.

Return type:

List[Tuple[FilamentRecord, float]]

Returns:

List of (filament_record, distance) tuples sorted by distance (closest first).

property makers: List[str]

Get sorted list of all makers.

property types: List[str]

Get sorted list of all types.

property finishes: List[str]

Get sorted list of all finishes.

get_override_info()[source]

Get information about user overrides in this filament palette.

Returns:

{
    "filaments": {
        "rgb": {"(r,g,b)": {"core": [sources], "user": [sources]}}
    },
    "synonyms": {
        "maker_name": {
            "type": "replaced|extended",
            "old": [core_synonyms],
            "new": [user_synonyms]
        }
    }
}

Return type:

Dictionary with override information structure

get_filament_by_id(filament_id)[source]

Get a filament by its ID.

Parameters:

filament_id (str) – Filament ID to look up

Return type:

Optional[FilamentRecord]

Returns:

FilamentRecord if found, None otherwise

list_owned()[source]

Get list of all owned filament records.

Return type:

List[FilamentRecord]

Returns:

List of FilamentRecord objects that are marked as owned (sorted by maker, type, color)

add_owned(filament_id, json_path=None)[source]

Add a filament ID to the owned list and save to file.

Parameters:

  • filament_id (str) – Filament ID to add

  • json_path (Path | str | None) – Optional path to owned-filaments.json file (uses default if None)

Raises:

ValueError – If the filament ID doesn’t exist in the database

Return type:

None

remove_owned(filament_id, json_path=None)[source]

Remove a filament ID from the owned list and save to file.

Parameters:

  • filament_id (str) – Filament ID to remove

  • json_path (Path | str | None) – Optional path to owned-filaments.json file (uses default if None)

Raises:

ValueError – If the filament ID is not in the owned list

Return type:

None

save_owned(json_path=None)[source]

Save the current owned filaments list to file.

Useful after programmatic modifications to owned_filaments set.

Parameters:

json_path (Path | str | None) – Optional path to owned-filaments.json file (uses default if None)

Return type:

None