Add new test, update cpthinges to new behavior

doc/rst/source/cookbook/features.rst

@@ -1139,16 +1139,19 @@ are identified as such via the special comment
 
 | ``# HARD_HINGE``
 
-and all hard hinges occur at data value *z = 0*.
+and all hard hinges occur at data value *z = 0* (but you can change this value by
+adding **+h**\ *value* to the name of the CPT).
 Other CPTs may instead have a *soft* hinge which indicates a natural hinge or transition
 point in the CPT itself, unrelated to any natural data set *per se*. These CPTs
 are flagged by the special comment
 
 | ``# SOFT_HINGE``
 
-CPTs with soft hinges behave as regular (non-hinge) CPTs *unless* the user
-appends **+h**\ [*hinge*] to the CPT name.  This modifier will convert the soft
+CPTs with soft hinges behave as regular (non-hinge) CPTs *unless* the user activates then by
+appending **+h**\ [*hinge*] to the CPT name.  This modifier will convert the soft
 hinge into a hard hinge at the user-specified data value *hinge* [which defaults to 0].
+Note that if your specified data range *excludes* an activated soft or hard hinge then we
+only perform color sampling from the *half* of the CPT that pertains to the data range.
 All dynamic CPTs will need to be stretched to the user's preferred range, and there
 are two modes of such scaling: Some CPTs designed for a specific application
 (again, the topographic relief is a good example) have a *default range*

doc/rst/source/create_cpt.rst_

@@ -1,6 +1,7 @@
 **-C**\ [*cpt*\ \|\ *master*\ [**+h**\ [*hinge*]][**+i**\ *zinc*][**+u**\ \|\ **U**\ *unit*] \|\ *color1,color2*\ [,\ *color3*\ ,...]]
-    Name of the CPT. If a GMT Master soft-hinge CPT (see :ref:`Of Colors and Color Legends`) then
-    you can enable the hinge at data value *hinge* [0] via **+h**.  For other CPTs, you may convert their *z*-values
+    Name of the CPT. If given a GMT Master soft-hinge CPT (see :ref:`Of Colors and Color Legends`) then
+    you can enable the hinge at data value *hinge* [0] via **+h**, whereas for hard-hinge CPTs you
+    can adjust the location of the hinge [0].  For other CPTs, you may convert their *z*-values
     from meter to another distance unit (append **+U**\ *unit*) or from another unit to meter (append **+u**\ *unit*),
     with *unit* taken from **e**\ \|\ **f**\ \|\ **k**\ \|\ **M**\ \|\ **n**\ \|\ **u**.
     Alternatively, give *color1,color2*\ [*,color3*\ ,...]

doc/rst/source/grd2cpt.rst

@@ -219,6 +219,22 @@ Optional Arguments
 
 .. include:: explain_transparency.rst_
 
+Color Hinges
+------------
+
+Some of the GMT master dynamic CPTs are actually two separate CPTs
+meeting at a *hinge*.  Usually, colors may change dramatically across
+the hinge, which is used to separate two different domains (e.g., land
+and ocean across the shoreline, for instance).  CPTs with a hinge will
+have their two parts stretched to the required range separately, i.e.,
+the bottom part up to the hinge will be stretched independently of the
+part from the hinge to the top, according to the prescribed new range.
+Hinges are either *hard* or *soft*.  Soft hinges must be *activated* by
+appending **+h**\ [*hinge*] to the CPT name.
+If the selected range does not include an activated soft or hard hinge then
+we only resample colors from the half of the CPT that pertains to the range.
+See :ref:`Of Colors and Color Legends` for more information.
+
 Discrete versus Continuous CPT
 ------------------------------
 

doc/rst/source/makecpt.rst

@@ -232,8 +232,11 @@ and ocean across the shoreline, for instance).  CPTs with a hinge will
 have their two parts stretched to the required range separately, i.e.,
 the bottom part up to the hinge will be stretched independently of the
 part from the hinge to the top, according to the prescribed new range.
-If the selected range does not include the hinge then no such partitioning
-takes place.
+Hinges are either *hard* or *soft*.  Soft hinges must be *activated* by
+appending **+h**\ [*hinge*] to the CPT name.
+If the selected range does not include an activated soft or hard hinge then
+we only resample colors from the half of the CPT that pertains to the range.
+See :ref:`Of Colors and Color Legends` for more information.
 
 Discrete versus Continuous CPT
 ------------------------------

doc/rst/source/use_cpt_grd.rst_

@@ -2,8 +2,9 @@
     Name of the CPT. Alternatively, supply the name of a GMT color master
     dynamic CPT [*turbo*, but we use *geo* for @earth_relief and *srtm* for @srtm_relief data] to
     automatically determine a continuous CPT from the grid's *z*-range; you may round the range
-    to the nearest multiple of *zinc* by adding **+i**\ *zinc*. If a GMT Master soft-hinge CPT
-    (see :ref:`Of Colors and Color Legends`) then you can enable the hinge at data value *hinge* [0] via **+h**.
+    to the nearest multiple of *zinc* by adding **+i**\ *zinc*. If given a GMT Master soft-hinge CPT
+    (see :ref:`Of Colors and Color Legends`) then you can enable the hinge at data value *hinge* [0] via **+h**,
+    whereas for hard-hinge CPTs you can adjust the location of the hinge [0].
     For other CPTs, you may convert their *z*-values from meter to another distance unit (append **+U**\ *unit*)
     or from another unit to meter (append **+u**\ *unit*), with *unit* taken from
     **e**\ \|\ **f**\ \|\ **k**\ \|\ **M**\ \|\ **n**\ \|\ **u**.

src/gmt_support.c

@@ -1201,7 +1201,7 @@ GMT_LOCAL struct CPT_Z_SCALE *support_cpt_parse (struct GMT_CTRL *GMT, char *fil
 GMT_LOCAL struct CPT_Z_SCALE *support_cpt_parse (struct GMT_CTRL *GMT, char *file, unsigned int direction, unsigned int *hinge_mode, double *z_hinge) {
 	/* CPT file arg is <file>[+h[<hinge>]][+u|U<unit>]
 	 * The +h modifier is used to turn a soft hinge in a CPT to a hard hinge at the user-selected z-value [0]
-	 * It has no effect on hard hinges. */
+	 * or to adjust the location of the hinge for an hard hinge CPT. */
 	enum gmt_enum_units u_number;
 	unsigned int mode = 0;
 	char *c = NULL;
@@ -7339,13 +7339,11 @@ struct GMT_PALETTE * gmtlib_read_cpt (struct GMT_CTRL *GMT, void *source, unsign
 				X->mode |= GMT_CPT_HARD_HINGE;
 				X->has_hinge = 1;
 			}
-			else if (strstr (line, "HARD_HINGE")) {	/* Hard hinge the user cannot override */
+			else if (strstr (line, "HARD_HINGE")) {	/* Hard hinge is always active */
 				X->mode |= GMT_CPT_HARD_HINGE;
 				X->has_hinge = 1;
-				if (hinge_mode)
-					GMT_Report (GMT->parent, GMT_MSG_VERBOSE, "Cannot override hard hinges in CPT %s with +h. Modifier is ignored.\n", cpt_file);
 			}
-			else if (strstr (line, "SOFT_HINGE"))	/* Soft hinge the user can turn to a hard hinge via +h[<value>] */
+			else if (strstr (line, "SOFT_HINGE"))	/* Soft hinge the user can activate to a hard hinge via +h[<value>] */
 				X->mode |= GMT_CPT_SOFT_HINGE;
 			continue;	/* Don't want this instruction to be also kept as a comment */
 		}
@@ -7446,9 +7444,9 @@ struct GMT_PALETTE * gmtlib_read_cpt (struct GMT_CTRL *GMT, void *source, unsign
 			continue;
 		}
 
-		if (hinge_mode && X->mode & GMT_CPT_SOFT_HINGE) { /* Activate a soft hinge for the CPT */
+		if (hinge_mode && ((X->mode & GMT_CPT_SOFT_HINGE) || (X->mode & GMT_CPT_HARD_HINGE))) { /* Activate a soft hinge for the CPT and/or adjust the hinge */
 			X->has_hinge = 1;
-			X->hinge = z_hinge;	/* This is now a user-selected hinge value */
+			X->hinge = z_hinge;	/* This is now the user-selected hinge value */
 		}
 
 		/* Here we have regular z-slices.  Allowable formats are
@@ -7941,22 +7939,17 @@ int gmtsupport_validate_cpt (struct GMT_CTRL *GMT, struct GMT_PALETTE *P, double
 	if (*z_low < P->hinge && *z_high > P->hinge) return ks;	/* Output range includes hinge, all is well */
 
 	/* Here we have a CPT with a hinge that is not included in the desired range.  Per policy:
-	 * If a hard hinge then we extend the range to reach the hinge and throw away the unreferenced CPT half.
-	 * If a soft hinge then we turn off the hinge.
+	 * We throw away the unreferenced CPT half and return the other relevant half.
 	 */
-	if (P->mode & GMT_CPT_HARD_HINGE) {	/* Output range excludes hard hinge, must move z_low or z_high to include the hinge */
-		if (*z_low >= P->hinge) {	/* Must exclude the below-hinge CPT colors entirely */
-			gmt_M_memcpy (P->data, &P->data[ks], P->n_colors-ks, struct GMT_LUT);
-			P->n_colors -= ks;
-			GMT_Report (GMT->parent, GMT_MSG_VERBOSE, "gmtsupport_validate_cpt: CPT hard hinge is outside actual data range - range adjusted to start at hinge %g and below-hinge CPT ignored.\n", *z_low);
-		}
-		else if (*z_high <= P->hinge) {	/* Must exclude the above-hinge CPT colors entirely */
-			P->n_colors = ks;
-			GMT_Report (GMT->parent, GMT_MSG_VERBOSE, "gmtsupport_validate_cpt: CPT hard hinge is outside actual data range - range adjusted to end at hinge %g and above-hinge CPT ingored.\n", *z_high);
-		}
+	if (*z_low >= P->hinge) {	/* Must exclude the below-hinge CPT colors entirely */
+		gmt_M_memcpy (P->data, &P->data[ks], P->n_colors-ks, struct GMT_LUT);
+		P->n_colors -= ks;
+		GMT_Report (GMT->parent, GMT_MSG_VERBOSE, "gmtsupport_validate_cpt: CPT hard hinge is outside actual data range - range adjusted to start at hinge %g and below-hinge CPT ignored.\n", *z_low);
+	}
+	else if (*z_high <= P->hinge) {	/* Must exclude the above-hinge CPT colors entirely */
+		P->n_colors = ks;
+		GMT_Report (GMT->parent, GMT_MSG_VERBOSE, "gmtsupport_validate_cpt: CPT hard hinge is outside actual data range - range adjusted to end at hinge %g and above-hinge CPT ingored.\n", *z_high);
 	}
-	else	/* Soft hinge outside range means we ignore the hinge */
-		GMT_Report (GMT->parent, GMT_MSG_VERBOSE, "gmtsupport_validate_cpt: CPT soft hinge requested via +h[<hinge>] is outside actual data range - hinge is ignored.\n");
 	/* Behave as a single CPT range with no hinge from now on */
 	P->has_hinge = 0;
 	return GMT_NOTSET;

test/psscale/cpthinges.sh

@@ -7,10 +7,10 @@ gmt begin cpthinges ps
 	# No hinge selected, continuous CPT
 	gmt makecpt -Cpolar -T100/300
 	gmt colorbar -Baf -Dx0/0+w16c+h -Y2c
-	# hinge selected at z=0 which is outside - so ignored - discrete CPT
+	# hinge selected at z=0 which is outside range so only use top half - discrete CPT
 	gmt makecpt -Cpolar+h -T100/300/20
 	gmt colorbar -Baf -Dx0/0+w16c+h -Y2c
-	# hinge selected at z=0 which is outside - so ignored - continuous CPT
+	# hinge selected at z=0 which is outside range so only use top half - continuous CPT
 	gmt makecpt -Cpolar+h -T100/300
 	gmt colorbar -Baf -Dx0/0+w16c+h -Y2c
 	# hinge selected at z=200 becoming a hard hinge - discrete CPT

test/psscale/hardsoft.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Further exploration of both soft and hard hinges
+
+ps=hardsoft.ps
+
+gmt makecpt -Cgeo -T-1/2 > t.cpt
+gmt psscale -Dx0/0+w6i+jBL -Ct.cpt -Bxaf -By+l"a)" -K -P -X0.75i > $ps
+gmt makecpt -Cgeo+h0.5 -T-1/2 > t.cpt
+gmt psscale -Dx0.75i/0+w6i+jBL -Ct.cpt -Bxaf -By+l"b)" -O -K >> $ps
+gmt makecpt -Cgeo+h-0.5 -T-1/2 > t.cpt
+gmt psscale -Dx1.5i/0+w6i+jBL -Ct.cpt -Bxaf -By+l"c)" -O -K >> $ps
+gmt makecpt -Cgeo -T1/2 > t.cpt
+gmt psscale -Dx2.25i/0+w6i+jBL -Ct.cpt -Bxaf -By+l"d)" -O -K >> $ps
+gmt makecpt -Cgeo -T-2/-1 > t.cpt
+gmt psscale -Dx3i/0+w6i+jBL -Ct.cpt -Bxaf -By+l"e)" -O -K >> $ps
+
+gmt makecpt -Cpolar -T-10/20 > t.cpt
+gmt psscale -Dx3.75i/0+w6i+jBL -Ct.cpt -Bxaf -By+l"f)" -O -K >> $ps
+gmt makecpt -Cpolar+h -T-10/20 > t.cpt
+gmt psscale -Dx4.5i/0+w6i+jBL -Ct.cpt -Bxaf -By+l"g)" -O -K >> $ps
+gmt makecpt -Cpolar+h-5 -T-10/20 > t.cpt
+gmt psscale -Dx5.26i/0+w6i+jBL -Ct.cpt -Bxaf -By+l"h)" -O -K >> $ps
+gmt makecpt -Cpolar+h -T0/20 > t.cpt
+gmt psscale -Dx6i/0+w6i+jBL -Ct.cpt -Bxaf -By+l"i)" -O -K >> $ps
+gmt makecpt -Cpolar+h-5 -T-10/-5 > t.cpt
+gmt psscale -Dx6.75i/0+w6i+jBL -Ct.cpt -Bxaf -By+l"j)" -O -K >> $ps
+gmt pstext -R0/6/-2/9 -Jx1i/-0.2i -Y6.5i -F+f10p+jBL -O -N<< EOF >> $ps
+0 0 a) -Cgeo -T-1/2 [Normal hard hinge behavior at z = 0]
+0 1 b) -Cgeo+h0.5 -T-1/2 [Relocate hard hinge to +0.5 km]
+0 2 c) -Cgeo+h-0.5 -T-1/2 [Relocate hard hinge to -0.5 km]
+0 3 d) -Cgeo -T1/2 [Range above hard hinge z = 0; lower CPT removed, no hinge]
+0 4 e) -Cgeo -T-2/-1 [Range below hard hinge z = 0; upper CPT removed, no hinge]
+0 5 f) -Cpolar -T-10/20 [Normal behavior is to ignore soft hinges]
+0 6 g) -Cpolar+h -T-10/20 [Activate hinge at z = 0]
+0 7 h) -Cpolar+h-5 -T-10/20 [Activate hinge at z = -5]
+0 8 i) -Cpolar+h -T0/20 [Activate hinge z = 0 but range above; lower CPT removed, no hinge]
+0 9 j) -Cpolar+h-5 -T-10/-5 [Activate hinge at z = -5 but range is below; upper CPT removed, no hinge]
+EOF