BRL-CAD
Loading...
Searching...
No Matches
color.h
Go to the documentation of this file.
1/* C O L O R . H
2 * BRL-CAD
3 *
4 * Copyright (c) 2004-2025 United States Government as represented by
5 * the U.S. Army Research Laboratory.
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public License
9 * version 2.1 as published by the Free Software Foundation.
10 *
11 * This library is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this file; see the file named COPYING for more
18 * information.
19 */
20
21#ifndef BU_COLOR_H
22#define BU_COLOR_H
23
24#include "common.h"
25
26#include "vmath.h"
27
28#include "bu/defines.h"
29#include "bu/magic.h"
30
32
33/** @addtogroup bu_color
34 * @brief
35 * Support for storing and manipulating color data.
36 */
37/** @{ */
38/** @file bu/color.h */
39
40#define RED 0
41#define GRN 1
42#define BLU 2
43#define ALP 3
44
45#define HUE 0
46#define SAT 1
47#define VAL 2
48
49
50/**
51 * a single color value, stored as a 0.0 to 1.0 triplet for RGBA
52 */
54{
56};
57typedef struct bu_color bu_color_t;
58#define BU_COLOR_NULL ((struct bu_color *) 0)
59
60/**
61 * initializes a bu_color struct without allocating any memory.
62 */
63#define BU_COLOR_INIT(_c) { \
64 (_c)->buc_rgb[RED] = (_c)->buc_rgb[GRN] = (_c)->buc_rgb[BLU] = 0; (_c)->buc_rgb[ALP] = 0; \
65 }
66
67/**
68 * Check whether two colors are equal within a tolerance.
69 */
70#define BU_COLOR_NEAR_EQUAL(_c1, _c2, _tol) \
71 HNEAR_EQUAL(_c1.buc_rgb, _c2.buc_rgb, _tol)
72
73
74/**
75 * macro suitable for declaration statement initialization of a bu_color
76 * struct. does not allocate memory.
77 */
78#define BU_COLOR_INIT_ZERO {{0, 0, 0, 0}}
79
80/* Initializers for commonly used colors */
81#define BU_COLOR_BLUE {{0, 0, 1, 0}}
82#define BU_COLOR_CYAN {{0, 1, 1, 0}}
83#define BU_COLOR_GREEN {{0, 1, 0, 0}}
84#define BU_COLOR_PURPLE {{1, 0, 1, 0}}
85#define BU_COLOR_RED {{1, 0, 0, 0}}
86#define BU_COLOR_WHITE {{1, 1, 1, 0}}
87#define BU_COLOR_YELLOW {{1, 1, 0, 0}}
88
89/**
90 * Copy a bu_color
91 */
92#define BU_COLOR_CPY(_dest, _src) {\
93 (_dest)->buc_rgb[RED] = (_src)->buc_rgb[RED]; \
94 (_dest)->buc_rgb[GRN] = (_src)->buc_rgb[GRN]; \
95 (_dest)->buc_rgb[BLU] = (_src)->buc_rgb[BLU]; \
96 (_dest)->buc_rgb[ALP] = (_src)->buc_rgb[ALP]; \
97}
98
99
100/** random color generating methods */
105
106/**
107 * Function to generate random color
108 *
109 * Refactoring points:
110 * truly random color
111 * 3dm-g: src/libgcv/plugins/rhino/rhino_read.cpp
112 * "constrained" random
113 * BRLCADWrapper:getRandomColor(): src/conv/step/BRLCADWrapper.cpp
114
115 */
117
118#if 0
119
120/**
121 * Refactoring points:
122 * color command (set specified color)
123 * src/libged/color.c
124 * src/libged/brep.c
125 * get color from string
126 * src/libbu/color.c
127
128* Possible calling syntax:
129 @code
130 * // draw a purely random color in 0/0/0 to 255/255/255 range
131 * bn_color_samples(colors, NULL, COLOR_RANDOM, 1); // problematic in libbu, random is libbn domain
132 *
133 * // draw a golden ratio distribution random color in 0/0/0 to 255/255/255 range, s=0.5, v=0.95
134 * bn_color_samples(colors, NULL, COLOR_RANDOM_LIGHTENED, 1); // problematic in libbu, random is libbn domain
135 *
136 * // draw bezier interpolated and lightened samples
137 * struct bu_color range[4] = {0};
138 * bu_color_from_str(&range[0], "#0f0"); // green
139 * bu_color_from_str(&range[1], "0.f/0.f/1.f") // blue
140 * bu_color_from_str(&range[2], "purple");
141 * bn_color_samples(colors, range, COLOR_LINEAR, 10); // 10 dark colors from green to blue to purple
142 *
143 * // return a standard "heat map" with 18 quantized samples
144 * bn_color_samples(colors, NULL, COLOR_STANDARD_HEAT, 18);
145 @endcode
146 *
147 * Need:
148 * way to map from different color specifications to color including
149 * name: "red"
150 * rgbint: 255/0/0
151 * rgbfloat: 1.0f/0f/0f
152 * hexint: #FF0000
153 * hexshort: #F00
154 * hsv: 0/100%/100%
155 * hsl: 0/100%/50%
156 * ignoring YCbCr, YPbPr, YUV, YIQ, CMYK, CIE LAB
157 * ignoring grayscale specification
158 */
159/**
160 * Return a set of sampled colors given a range of zero or more colors
161 * (a NULL-terminated list of colors), a sample method, and desired
162 * number of color samples to return.
163 *
164 * Specifying no colors implies full spectrum. The default sampling
165 * method uses a golden ratio distribution to give a "balanced" random
166 * distribution that is effective with dark backgrounds and/or text.
167 *
168 * Returns the number of samples allocated.
169 */
170size_t bn_color_samples(struct bu_color **samples, const bu_color *colors, enum sampleMethod, size_t numSamples);
171#endif
172
173
174/**
175 * Convert between RGB and HSV color models
176 *
177 * R, G, and B are in {0, 1, ..., 255},
178 *
179 * H is in [0.0, 360.0), and S and V are in [0.0, 1.0],
180 *
181 * If S == 0.0, H is achromatic and set to 0.0
182 *
183 * These two routines are adapted from:
184 * pp. 592-3 of J.D. Foley, A. van Dam, S.K. Feiner, and J.F. Hughes,
185 * _Computer graphics: principles and practice_, 2nd ed., Addison-Wesley,
186 * Reading, MA, 1990.
187 */
188BU_EXPORT extern void bu_rgb_to_hsv(const unsigned char *rgb, fastf_t *hsv);
189BU_EXPORT extern int bu_hsv_to_rgb(const fastf_t *hsv, unsigned char *rgb);
190
191
192/**
193 * Utility functions to convert between various containers
194 * for color handling.
195 *
196 * FIXME: inconsistent input/output parameters!
197 * TODO: consider stdarg ... to consolidate all the _from_ functions, e.g.,
198 * // 3 colors
199 * bu_color_create(struct bu_color **colors, "red", "0/255/0", "#0000ff", NULL);
200 *
201 * // 2 colors from existing data
202 * struct bu_color *colors = NULL;
203 * bu_color_create(&colors, "%d/%d/%d", rgb[0], rgb[1], rgb[2], "hsv(%lf,0.5,0.95)", hsv, NULL);
204 * bu_color_destroy(colors);
205 */
206BU_EXPORT extern int bu_color_from_rgb_floats(struct bu_color *cp, const fastf_t *rgb);
207BU_EXPORT extern int bu_color_from_rgb_chars(struct bu_color *cp, const unsigned char *rgb);
208BU_EXPORT extern int bu_color_from_str(struct bu_color *cp, const char *str);
209/* UNIMPLEMENTED: BU_EXPORT extern int bu_color_from_hsv_floats(struct bu_color *cp, fastf_t *hsv); */
211BU_EXPORT extern int bu_str_to_rgb(const char *str, unsigned char *rgb); /* inconsistent, deprecate */
212
213BU_EXPORT extern int bu_color_to_rgb_floats(const struct bu_color *cp, fastf_t *rgb); /* bu_color_as_rgb_3fv */
214BU_EXPORT extern int bu_color_to_rgb_chars(const struct bu_color *cp, unsigned char *rgb); /* bu_color_as_rgb */
215BU_EXPORT extern int bu_color_to_rgb_ints(const struct bu_color *cp, int *r, int *g, int *b); /* bu_color_as_rgb_3i */
216/* UNIMPLEMENTED: BU_EXPORT extern int bu_color_to_hsv_floats(struct bu_color *cp, fastf_t *hsv); */ /* bu_color_as_hsv_3fv */
218
219/** @} */
220
222
223#endif /* BU_COLOR_H */
224
225/*
226 * Local Variables:
227 * mode: C
228 * tab-width: 8
229 * indent-tabs-mode: t
230 * c-file-style: "stroustrup"
231 * End:
232 * ex: shiftwidth=4 tabstop=8
233 */
Definition dvec.h:74
Header file for the BRL-CAD common definitions.
int bu_color_to_rgb_ints(const struct bu_color *cp, int *r, int *g, int *b)
int bu_color_from_str(struct bu_color *cp, const char *str)
int bu_color_from_rgb_floats(struct bu_color *cp, const fastf_t *rgb)
void bu_rgb_to_hsv(const unsigned char *rgb, fastf_t *hsv)
int bu_str_to_rgb(const char *str, unsigned char *rgb)
int bu_hsv_to_rgb(const fastf_t *hsv, unsigned char *rgb)
int bu_color_from_rgb_chars(struct bu_color *cp, const unsigned char *rgb)
bu_color_rand_t
Definition color.h:101
int bu_color_rand(struct bu_color *c, bu_color_rand_t type)
int bu_color_to_rgb_chars(const struct bu_color *cp, unsigned char *rgb)
int bu_color_to_rgb_floats(const struct bu_color *cp, fastf_t *rgb)
@ BU_COLOR_RANDOM
Definition color.h:102
@ BU_COLOR_RANDOM_LIGHTENED
Definition color.h:103
void int * c
Definition tig.h:139
double fastf_t
fastest 64-bit (or larger) floating point type
Definition vmath.h:334
fastf_t hvect_t[ELEMENTS_PER_HVECT]
4-tuple vector
Definition vmath.h:361
Global registry of recognized magic numbers.
hvect_t buc_rgb
Definition color.h:55
fundamental vector, matrix, quaternion math macros