---

12.3.12.4 EPS files (eps.h)

The Encapsulated PostScript (EPS) format is commonly used to store images (or individual/single-page parts of a document) in the PostScript documents. For a more complete introduction, please see Recognized file formats. To provide high quality graphics, the Postscript language is a vectorized format, therefore pixels (elements of a “rasterized” format) are not defined in their context.

To display rasterized images, PostScript does allow arrays of pixels. However, since the over-all EPS file may contain many vectorized elements (for example, borders, text, or other lines over the text) and interpreting them is not trivial or necessary within Gnuastro’s scope, Gnuastro only provides some functions to write a dataset (in the gal_data_t format, see Generic data container (gal_data_t)) into EPS.

Macro: GAL_EPS_MARK_COLNAME_TEXT ¶

Macro: GAL_EPS_MARK_COLNAME_FONT ¶

Macro: GAL_EPS_MARK_COLNAME_XPIX ¶

Macro: GAL_EPS_MARK_COLNAME_YPIX ¶

Macro: GAL_EPS_MARK_COLNAME_SHAPE ¶

Macro: GAL_EPS_MARK_COLNAME_COLOR ¶

Macro: GAL_EPS_MARK_COLNAME_SIZE1 ¶

Macro: GAL_EPS_MARK_COLNAME_SIZE2 ¶

Macro: GAL_EPS_MARK_COLNAME_ROTATE ¶

Macro: GAL_EPS_MARK_COLNAME_FONTSIZE ¶

Macro: GAL_EPS_MARK_COLNAME_LINEWIDTH ¶

Name of column that the required property will be read from.

Macro: GAL_EPS_MARK_DEFAULT_SHAPE ¶

Macro: GAL_EPS_MARK_DEFAULT_COLOR ¶

Macro: GAL_EPS_MARK_DEFAULT_SIZE1 ¶

Macro: GAL_EPS_MARK_DEFAULT_SIZE2 ¶

Macro: GAL_EPS_MARK_DEFAULT_SIZE2_ELLIPSE ¶

Macro: GAL_EPS_MARK_DEFAULT_ROTATE ¶

Macro: GAL_EPS_MARK_DEFAULT_LINEWIDTH ¶

Macro: GAL_EPS_MARK_DEFAULT_FONT ¶

Macro: GAL_EPS_MARK_DEFAULT_FONTSIZE ¶

Default values for the various mark properties. These constants will be used if the caller has not provided any of the given property.

Function:
int
gal_eps_name_is_eps (char *name) ¶

Return 1 if name has an EPS suffix. This can be used to make sure that a given input file is EPS. See gal_eps_suffix_is_eps for a list of recognized suffixes.

Function:
int
gal_eps_suffix_is_eps (char *name) ¶

Return 1 if suffix is a recognized EPS suffix. The recognized suffixes are .eps, .EPS, .epsf, .epsi.

Function:
void
gal_eps_to_pt (float widthincm, size_t *dsize, size_t *w_h_in_pt) ¶

Given a specific width in centimeters (widthincm and the number of he dataset’s pixels in each dimension (dsize) calculate the size of he output in PostScript points. The output values are written in the w_h_in_pt array (which has to be allocated before calling this unction). The first element in w_h_in_pt is the width and the second is the height of the image.

Function:
uint8_t
gal_eps_shape_name_to_id (char *name) ¶

Return the shape ID of a mark from its name (which is not case-sensitive).

Function:
uint8_t
gal_eps_shape_id_to_name (uint8_t id) ¶

Return the shape name from its ID.

Function:
void
gal_eps_write (gal_data_t *in, char *filename, float widthincm, uint32_t borderwidth, uint8_t bordercolor, int hex, int dontoptimize, int forps, gal_data_t *marks) ¶

Write the in dataset into an EPS file called filename. in has to be an unsigned 8-bit character type GAL_TYPE_UINT8, see Numeric data types). The desired width of the image in human/non-pixel units can be set with he widthincm argument. If borderwidth is non-zero, it is interpreted as the width (in points) of a solid black border around the mage. A border can helpful when importing the EPS file into a document. The color of the border can be set with bordercolor, use the macros in Color functions (color.h). If forpdf is not zero, the output can be imported into a Postscript file directly (not as an “encapsulated” postscript, which is the default).

EPS files are plain-text (can be opened/edited in a text editor), therefore there are different encodings to store the data (pixel values) within them. Gnuastro supports the Hexadecimal and ASCII85 encoding. ASCII85 is more efficient (producing small file sizes), so it is the default encoding. To use Hexadecimal encoding, set hex to a non-zero value.

By default, when the dataset only has two values, this function will use the PostScript optimization that allows setting the pixel values per bit, not byte (Recognized file formats). This can greatly help reduce the file size. However, when dontoptimize!=0, this optimization is disabled: even though there are only two values (is binary), the difference between them does not correspond to the full contrast of black and white.

If marks!=NULL, it is assumed to contain multiple columns of information to draw marks over the background image. The multiple columns are a linked list of 1D gal_data_t of the same size (number of rows) that are connected to each other through the next element (this is the same format that Gnuastro’s library uses for tables, see Table input output (table.h) or Library demo - reading and writing table columns).

The macros defined above that have the format of GAL_EPS_MARK_COLNAME_* show all the possible columns that you can provide in this linked list. Only the two coordinate columns are mandatory (GAL_EPS_MARK_COLNAME_XPIX and GAL_EPS_MARK_COLNAME_YPIX. If any of the other properties is not in the linked list, then the default properties of the GAL_EPS_MARK_DEFAULT_* macros will be used (also defined above.

The columns are identified based on the name element of Gnuastro’s generic data structure (see Generic data container (gal_data_t)). The names must have the pre-defined names of the GAL_EPS_MARK_COLNAME_* macros (case sensitive). Therefore, the order of columns in the list is irrelevant!