/ 
Sew-Color-1.05
River stage zero No dependents
/ Sew::Color

NAME

Sew:Color - rgb colours for various manufactures of coloured embroidery thread.

ABSTRACT

Extensible Module for determining rgb colours of various manufacturers of embroidering thread 
and the codes that go with them.

SYNOPSIS

use Sew::Color
my @rgb=rgb('Brother', '502'); 
my $name=name('Brother','502'); 

print "$name (@rgb)\n"; 
my @m=manlist();

DESCRIPTION

 These calls return respectively the red green and blue components of the colour of the thread 
 and the 'English' name of the thread colour. The colour components will be in the range 0 to 255. 
 In this case, Brother thread number 502. 
 Be aware that the name of the thread colour is not unique, there are some codes that have 
 the same name, although they are mostly different. 

 The above code prints out 
    
    Mint Green (148 190 140) 

 code(Manufacturer,red,green.blue)

 This function does a simple search in the colour space to find the colour that is closest to the rgb values you provide. 

 The parameters are

   Manufacturer: Can be a single manufacturer, a comma seperated list or an array reference of manufacturers. 
   				 It can be empty to search all known about. 
   red, green, blue are the colour co-ordinates to search for. Distnce is done through a very simple sequential search
                 using a simple 3-d colour model without any weightings. (so rgb all treated the same.) 

 The return values are: 

	In a scalar context, just the code, for example '502'. 
	In an array context it returns a 3 element array, with the following entries

		Thread code, eg '502'
		Manufacturer, eg 'Brother' 
		Error distance, eg 42. This is the distance in linear units scaled to 255 
		between the thread found and the desired colour. Note that it can be more than 255
		(Consider that the diagonal of a cube with side 255 is more than 255. ) but will normally 
		not be.

     Note that only one result is returned, and this ought tobe changed, all nearest results should be found.

The function manlist() returns an array of the names of the manufacturers supported.

Custom Searches

If you only have certain threads that you want to search (you dont happen to have the full Madeira
in your store cupboard!) you can say which ones you do have by using the custom function. This is called as follows

  custom('Manufacturer',list of codes, 'Manufacturer', list of codes ) 

A call to the code function with the special string 'custom' as manufacturer will search only these threads. 

  custom() 

will reset all the custom threads. 

Multiple calls to custom where the argument list is not empty will add each new set to the custom search list. 

The special keyword all may be used with the custom function to either add all the threads for a manufacturer, or to add all threads of all manufacturers. so custom('Brother','all') would add all Brother threads, while custom('all') would add all known threads. Once added individual threads or sets can be removed with the custom_sub function. 

custom_sub() takes parameters similar to custom and will remove specific threads from the custom search list.

Methods

rgb(Manufacturer, code) returns a 255-max scaled rgb tripplet. 
name(Manufacturer,code) returns the "English" name of the colour. 
code(Manufacturer-list,r,g,b)  returns either the code or an array 
						with the following: (Manufacturer,code,error distance)

CAVEAT

All should be aware that giving an rgb value for a thread colour will never be anything more than an approximation at best, even assuming 
the values are right. Be aware that many thread manufacturers give or sell colour cards that have actual samples of the thread on, because even 
using paint on paper has proved so unsatisfactory. Really I cannot say it loud enough, trying to represent real-world colours that are not 
a photograph, using rgb values is massively approximate at best. For example, it depends on the angle of the light, the amount of 
light, the type of light and other factors. Or it may not. I have seen materials that change colour quite noticibly depending on weather they 
are viewed by sunlight, incandescent light or flourscent light. Its a manufacturers nightmare, but it happens.

PROCESS

In the main these values were derived by me by taking a web page which has a photograph of the thread, cropping it to remove anything like a shadow, 
changing the size to 1 by 1 pixcel (so that all other pixcels are averaged) and then listing the colour of that pixcel. 

This results in rather real-world values - the extreme ends of the scale near 0 and 255 do not appear and the colours are a bit less saturated than...
well then you might think. 

Sulky helpfully provide a spreadsheet with rgb values. It would be a bit silly not to use it, wouldnt it? But the truth is that the values 
you get are very different since they have clearly been normalised in some way so that blacks are fully black and whites are fully white. 

For example, Sulky "Black" 942-1005 has rgb values (0,0,0) in the spreadsheet. But using the other method, has rgb values (44,42,44). 

Which is right? The answer is of course that both are, and you need to use the values obtained carefully and sensibly, processing them if needed. 

Sulky do this (perhaps) because in part you are throwing away some of the precision in your 8 bit representation if you say the lowest value 
I am going to have is 42. They are (probably) not happy using 8 bits any way, because from there perspective this is not much precision to 
represent a world of colour, why throw some of it away?  

Which Sulky values did I include? In the end I included the real-world values since thats more compatible with the other manufacturers in the 
package. Let me know if you think I should do other wise. It also allows me to easily include varigated threads (that have a delibneratly 
variable colour along its length) since this will be correctly averaged.

EXTENSION

The module may be extended to a new manufacturer by adding lines of the following format to the module:

manufacturer,english name,code,red,green,blue

for example the line Brother,Moss Green,515,48,125,38

is responsible for the Moss Green number 515 entry.

BUGS and the like

There are many manufacturers not covered. 

If you use this please drop me an email to say it has been useful (or not) to you. 

The sat() function generally returned 255 in version 1.04. This is fixed in 1.05

AUTHOR

Mark Winder June 2012. 
markwin (at) cpan.org